From a5b2d4fb2ec126edf5abc285010b9da1d7b42c6d Mon Sep 17 00:00:00 2001 From: Oleg Nenashev Date: Thu, 24 Nov 2016 01:23:57 +0100 Subject: [PATCH 01/15] Docs: Rename README to a standard name --- README.markdown => README.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename README.markdown => README.md (100%) diff --git a/README.markdown b/README.md similarity index 100% rename from README.markdown rename to README.md From b14dcf3aaa877d7dda232cb42a1a49ffd6792f77 Mon Sep 17 00:00:00 2001 From: Oleg Nenashev Date: Thu, 24 Nov 2016 01:32:26 +0100 Subject: [PATCH 02/15] Get rid of the bottom links --- README.md | 25 ++++++++----------------- 1 file changed, 8 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index 8ccdcfa..4217c15 100644 --- a/README.md +++ b/README.md @@ -49,7 +49,7 @@ Your renamed `winsw.exe` accepts the following commands: Error reporting --------------- -Winsw uses WMI underneath, and as such it uses its error code as the exit code. See the MSDN article [Create method of the Win32_Service class] for the complete list of exit code. +Winsw uses WMI underneath, and as such it uses its error code as the exit code. See the MSDN article [Create method of the Win32_Service class](http://msdn.microsoft.com/en-us/library/aa389390(VS.85).aspx) for the complete list of exit code. When winsw is running as a service, more detailed error information is reported to the Windows event log. @@ -194,7 +194,7 @@ This element specifies the arguments to be passed to the executable. Winsw will For backward compatibility, `` element can be used instead to specify the whole command line in a single element. ### stopargument/stopexecutable -When the service is requested to stop, winsw simply calls [TerminateProcess] API to kill the service instantly. However, if `` elements are present, winsw will instead launch another process of `` (or `` if that's specified) with the `` arguments, and expects that to initiate the graceful shutdown of the service process. +When the service is requested to stop, winsw simply calls [TerminateProcess function](http://msdn.microsoft.com/en-us/library/windows/desktop/ms686714(v=vs.85).aspx ) API to kill the service instantly. However, if `` elements are present, winsw will instead launch another process of `` (or `` if that's specified) with the `` arguments, and expects that to initiate the graceful shutdown of the service process. Winsw will then wait for the two processes to exit on its own, before reporting back to Windows that the service has terminated. @@ -210,7 +210,7 @@ When you use the ``, you must use `` instead of `` below for how to specify time duration: @@ -290,7 +290,7 @@ Possible values are `idle`, `belownormal`, `normal`, `abovenormal`, `high`, `rea idle -Specifying a priority higher than normal has unintended consequences. See the MSDN article [ProcessPriorityClass Enumeration] for details. This feature is intended primarily to launch a process in a lower priority so as not to interfere with the computer's interactive usage. +Specifying a priority higher than normal has unintended consequences. See the MSDN article [ProcessPriorityClass Enumeration](http://msdn.microsoft.com/en-us/library/system.diagnostics.processpriorityclass(v=vs.110).aspx) for details. This feature is intended primarily to launch a process in a lower priority so as not to interfere with the computer's interactive usage. ###stopparentprocessfirst Optionally specify the order of service shutdown. If true, the parent process is shutdown first. This is useful when the main process is a console, which can respond to Ctrl+C command and will gracefully shutdown child processes @@ -304,26 +304,17 @@ Developer info ### Project status * WinSW 1.x - Maintenance only - * [winsw-1.17] fixes the most of active issues - * [winsw-1.17-beta.2] is available for the evaluation + * [winsw-1.17](https://github.com/kohsuke/winsw/milestones/winsw-1.17) fixes the most of active issues + * [winsw-1.17-beta.2](https://github.com/kohsuke/winsw/releases/tag/1.17-beta.2) is available for the evaluation * New versions may be released on-demand * All new fixes will be ported to WinSW-2.x * WinSW 2.x - Active development, no stable releases available - * [winsw-2.0] - Current development branch + * [winsw-2.0](https://github.com/kohsuke/winsw/milestones/winsw-2.0) - Current development branch * API stability is not guaranteed till the first release, the project structure is in flux ### Build Environment -* IDE: [Visual Studio Community 2013][MVS2013] (free for open-source projects) +* IDE: [Visual Studio Community 2013](http://www.visualstudio.com/en-us/news/vs2013-community-vs.aspx) (free for open-source projects) * winsw_cert.pfx should be available in the project's root * You can generate the certificate in "Project Settings/Signing" * The certificate is in .gitignore list. Please do not add it to the repository - -[MVS2013]: http://www.visualstudio.com/en-us/news/vs2013-community-vs.aspx -[winsw-1.17]: https://github.com/kohsuke/winsw/milestones/winsw-1.17 -[winsw-1.17-beta.2]: https://github.com/kohsuke/winsw/releases/tag/1.17-beta.2 -[WinSW-2.0]: https://github.com/kohsuke/winsw/milestones/winsw-2.0 -[TerminateProcess]: http://msdn.microsoft.com/en-us/library/windows/desktop/ms686714(v=vs.85).aspx "TerminateProcess function" -[Create method of the Win32_Service class]: http://msdn.microsoft.com/en-us/library/aa389390(VS.85).aspx -[send Ctrl+C signal to the process]: http://msdn.microsoft.com/en-us/library/windows/desktop/ms683155(v=vs.85).aspx "GenerateConsoleCtrlEvent function" -[ProcessPriorityClass Enumeration]: http://msdn.microsoft.com/en-us/library/system.diagnostics.processpriorityclass(v=vs.110).aspx From 0e7cc49692579e83f20b7ae21771f5d5de43113e Mon Sep 17 00:00:00 2001 From: Oleg Nenashev Date: Thu, 24 Nov 2016 06:02:30 +0300 Subject: [PATCH 03/15] Decouple the documentation to several pages --- README.md | 309 +++----------------------------- doc/deferredFileOperations.md | 20 +++ doc/installation.md | 77 ++++++++ doc/loggingAndErrorReporting.md | 58 ++++++ doc/selfRestartingService.md | 16 ++ doc/xmlConfigFile.md | 223 +++++++++++++++++++++++ 6 files changed, 418 insertions(+), 285 deletions(-) create mode 100644 doc/deferredFileOperations.md create mode 100644 doc/installation.md create mode 100644 doc/loggingAndErrorReporting.md create mode 100644 doc/selfRestartingService.md create mode 100644 doc/xmlConfigFile.md diff --git a/README.md b/README.md index 4217c15..caf32e1 100644 --- a/README.md +++ b/README.md @@ -1,42 +1,25 @@ winsw: Windows service wrapper in less restrictive license ========================= -Why? ----- -Now, I think the first question that people would ask is, why another, when there's [Java Service Wrapper project](http://wrapper.tanukisoftware.org/doc/english/download.jsp) already available. The main reason for writing my own was the license — Java Service Wrapper project is in GPL (so that they can sell their commercial version in a different license), and that made it difficult for [Jenkins](http://jenkins-ci.org/) (which is under the MIT license) to use it. +### Why? + +Now, I think the first question that people would ask is, why another, when there's [Java Service Wrapper project](http://wrapper.tanukisoftware.org/doc/english/download.jsp) already available. +The main reason for writing my own was the license — Java Service Wrapper project is in GPL (so that they can sell their commercial version in a different license), and that made it difficult for [Jenkins](http://jenkins-ci.org/) (which is under the MIT license) to use it. -Functionality-wise, there's really not much that's worth noting; the problem of wrapping a process as a Windows service is so well defined that there aren't really any room for substantial innovation. You basically write a configuration file specifying how you'd like your process to be launched, and we provide programmatic means to install/uninstall/start/stop services. Another notable difference is that winsw can host any executable, whereas Java Service Wrapper can only host Java apps. Whether you like this or not depends on your taste, so I wouldn't claim mine is better. It's just different. +Functionality-wise, there's really not much that's worth noting; the problem of wrapping a process as a Windows service is so well defined that there aren't really any room for substantial innovation. +You basically write a configuration file specifying how you'd like your process to be launched, and we provide programmatic means to install/uninstall/start/stop services. +Another notable difference is that winsw can host any executable, whereas Java Service Wrapper can only host Java apps. + +Whether you like this or not depends on your taste, so I wouldn't claim mine is better. +It's just different. -As the name implies, this is for Windows only. Unix systems have their own conventions for daemons, so a good behaving Unix daemon should just be using launchd/upstart/SMF/etc, instead of custom service wrapper. +As the name implies, this is for Windows only. +Unix systems have their own conventions for daemons, so a good behaving Unix daemon should just be using `launchd/upstart/SMF/etc`, instead of custom service wrapper. -Download --------- +### Download [Binaries are available here](http://repo.jenkins-ci.org/releases/com/sun/winsw/winsw/) -Usage ------ -You write the configuration file that defines your service. This is the one I use for Jenkins: - - - jenkins - Jenkins - This service runs Jenkins continuous integration system. - - java - -Xrs -Xmx256m -jar "%BASE%\jenkins.war" --httpPort=8080 - rotate - - -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. - -Available commands ------------------- +### Available commands Your renamed `winsw.exe` accepts the following commands: * `install` to install the service to Windows Service Controller @@ -46,260 +29,16 @@ Your renamed `winsw.exe` accepts the following commands: * `restart` to restart the service. If the service is not currently running, this command acts like `start`. * `status` to check the current status of the service. This command prints one line to the console. `NonExistent` to indicate the service is not currently installed, `Started` to indicate the service is currently running, and `Stopped` to indicate that the service is installed but not currently running. - -Error reporting ---------------- -Winsw uses WMI underneath, and as such it uses its error code as the exit code. See the MSDN article [Create method of the Win32_Service class](http://msdn.microsoft.com/en-us/library/aa389390(VS.85).aspx) for the complete list of exit code. - -When winsw is running as a service, more detailed error information is reported to the Windows event log. - -Deferred file operations ------------------------- -To support self updating services, winsw offers a mechanism to perform file operations before the process you specified in the configuration file gets launched. This is often necessary because Windows prevents files from overwritten while it's in use. - -To perform file operations, write a text file (in the UTF-8 encoding) at `myapp.copies` (that is, it's in the same directory as `myapp.xml` and `myapp.exe` but with a different file extension), and for each operation add one line: - -* To move a file, write a line `src>dst`. If the `dst` file already exists it will be overwritten. - -The success or failure of these operations will be recorded in the event log. - -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. -I have 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. -Also see `WINSW_EXECUTABLE` environment variable. - -The `` element in the configuration file also provides an useful building block for a self updating services. - -Restarting service from itself ------------------------------- -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. -To restart the service from within, execute `%WINSW_EXECUTABLE% restart!`. Note that you are invoking `restart!` command, not `restart` command. This hidden command is a flavor of the `restart` operation, where winsw creates another winsw process in a separate process group, and restarts the service from there. - -This additional indirection is necessary because Windows Service Control Manager (SCM) will kill child processes recursively when it stops a service. SCM doesn't provide the restart operation as an atomic operation either, so winsw implements restart by a sequence of stop and start. The 2nd winsw process in a separate process group ensures that winsw can survive this massacre to -execute the start call. - - -Logging -------- -Winsw supports several different ways to capture stdout and stderr from the process you launch. - -### Log directory -The `` 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) -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. - - - -### Reset mode -Works like the append mode, except that every time the service starts, the old log files are truncated. - - - -### Ignore mode -Throw away stdout and stderr, and do not produce any log files at all. - - - -### 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 `` element specifies the rotation threshold in KB (defaults to 10MB), and the nested `` element specifies the number of rotated files to keep (defaults to 8.) - - - 10240 - 8 - - -### 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. - -This configuration must accompany a nested `` element, which specifies the timestamp pattern used as the log file name. - - - yyyyMMdd - - -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`. - - -Offline Environment 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: - - - - - - - -See [KB 936707](http://support.microsoft.com/kb/936707) for more details. - -.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`. - - - - - - - - -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. To our knowledge, none of the other flags are needed. - -Environment Variable Expansion in Configuration File ----------------------------------------------------- -Configuration XML files can include environment variable expansions of the form `%Name%`. Such occurences, if found, will be automatically replaced by the actual values of the variables. If an undefined environment variable is referenced, no substituion occurs. - -Configuration File Syntax -------------------------- -The behavior of the service is controlled by the XML configuration file. The root element of this XML file must be ``, and it supports the following child element. - -### id -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 (while I haven't verified this) this must consist entirely out of alpha-numeric characters. - -### name -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 -Long human-readable description of the service. This gets displayed in Windows service manager when the service is selected. - -### executable -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.) - -### startmode - Optional Element -This element specifies the start mode of the Windows service. It can be one of the following values: Boot, System, Automatic, or Manual. See [MSDN](https://msdn.microsoft.com/en-us/library/aa384896%28v=vs.85%29.aspx) for details. The default is Automatic. - -### depend -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. - -Multiple elements can be used to specify multiple dependencies. - - Eventlog - W32Time - -### logging - -Optionally set a different logging directory with and startup : reset (clear log), roll (move to \*.old) or append (default). - -### argument -This element specifies the arguments to be passed to the executable. Winsw will quote each argument if necessary, so do not put quotes in `` to avoid double quotation. - - arg1 - arg2 - arg3 - -For backward compatibility, `` element can be used instead to specify the whole command line in a single element. - -### stopargument/stopexecutable -When the service is requested to stop, winsw simply calls [TerminateProcess function](http://msdn.microsoft.com/en-us/library/windows/desktop/ms686714(v=vs.85).aspx ) API to kill the service instantly. However, if `` elements are present, winsw will instead launch another process of `` (or `` if that's specified) with the `` arguments, and expects that to initiate the graceful shutdown of the service process. - -Winsw will then wait for the two processes to exit on its own, before reporting back to Windows that the service has terminated. - -When you use the ``, you must use `` instead of ``. See the complete example below: - - catalina.sh - jpda - run - - catalina.sh - stop - -Note that the name of the element is `startargument` and not `startarguments`. As such, to specify multiple arguments, you'll specify multiple elements. - -### stoptimeout -When the service is requested to stop, winsw first attempts to [GenerateConsoleCtrlEvent function](http://msdn.microsoft.com/en-us/library/windows/desktop/ms683155(v=vs.85).aspx) (similar to Ctrl+C), then wait for up to 15 seconds for the process to exit by itself gracefully. A process failing to do that (or if the process does not have a console), then winsw resorts to calling [TerminateProcess function](http://msdn.microsoft.com/en-us/library/windows/desktop/ms686714(v=vs.85).aspx ) API to kill the service instantly. - -This optional element allows you to change this "15 seconds" value, so that you can control how long winsw gives the service to shut itself down. See `` below for how to specify time duration: - - 10sec - -### env -This optional element can be specified multiple times if necessary to specify environment variables to be set for the child process. The syntax is: - - - -### 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: - - - -Note that since the introduction UAC (Windows Vista and onward), services are no longer really allowed to interact with the desktop. In those OSes, all that this does is to allow the user to switch to a separate window station to interact with the service. - -### beeponshutdown -This optional element is to emit [simple tone](http://msdn.microsoft.com/en-us/library/ms679277%28VS.85%29.aspx) when the service shuts down. This feature should be used only for debugging, as some operating systems and hardware do not support this functionality. - -### download -This optional element can be specified multiple times to have the service wrapper retrieve resources from URL and place it locally as a file. This operation runs when the service is started, before the application specified by `` is launched. - - - -This is another useful building block for developing a self-updating service. - -### log -See the "Logging" section above for more details. - -### onfailure -This optional repeatable element controls the behaviour when the process launched by winsw fails (i.e., exits with non-zero exit code). - - - - - -For example, the above configuration causes the service to restart in 10 seconds after the first failure, restart in 20 seconds after the second failure, then Windows will reboot if the service fails one more time. - -Each element contains a mandatory `action` attribute, which controls what Windows SCM will do, and optional `delay` attribute, which controls the delay until the action is taken. The legal values for action are: - -* `restart`: restart the service -* `reboot`: reboot Windows -* `none`: do nothing and leave the service stopped - -The possible suffix for the delay attribute is sec/secs/min/mins/hour/hours/day/days. If missing, the delay attribute defaults to 0. - -If the service keeps failing and it goes beyond the number of `` configured, the last action will be repeated. Therefore, if you just want to always restart the service automatically, simply specify one `` element like this: - - - -### resetfailure -This optional element controls the timing in which Windows SCM resets the failure count. For example, if you specify `1 hour` and your service continues to run longer than one hour, then the failure count is reset to zero. This affects the behaviour of the failure actions (see `` above). - -In other words, this is the duration in which you consider the service has been running successfully. Defaults to 1 day. - -### Service account -It is possible to specify the useraccount (and password) that the service will run as. To do this, specify a `` element like this: - - - YOURDOMAIN - useraccount - Pa55w0rd - true - - -The `` is optional. If set to true, will automatically set the "Allow Log On As A Service" right to the listed account. - -### Working directory -Some services need to run with a working directory specified. To do this, specify a `` element like this: - - C:\application - -### priority -Optionally specify the scheduling priority of the service process (equivalent of Unix nice) -Possible values are `idle`, `belownormal`, `normal`, `abovenormal`, `high`, `realtime` (case insensitive.) - - idle - -Specifying a priority higher than normal has unintended consequences. See the MSDN article [ProcessPriorityClass Enumeration](http://msdn.microsoft.com/en-us/library/system.diagnostics.processpriorityclass(v=vs.110).aspx) for details. This feature is intended primarily to launch a process in a lower priority so as not to interfere with the computer's interactive usage. - -###stopparentprocessfirst -Optionally specify the order of service shutdown. If true, the parent process is shutdown first. This is useful when the main process is a console, which can respond to Ctrl+C command and will gracefully shutdown child processes -``` -true -``` - -Developer info ----------------------- +### Documentation + +* [Installation Guide](doc/protocols.md) - Describes the installation process for different systems and .NET versions +* Configuration: + * [Main XML Configuration file](doc/xmlConfigFile.md) + * [Configuration File](doc/xmlConfigFile.md) + * [Logging and Error Reporting](doc/loggingAndErrorReporting.md) +* Use-cases: + * [Self-restarting services](doc/selfRestartingService.md) + * [Deferred File Operations](doc/deferredFileOperations.md) ### Project status diff --git a/doc/deferredFileOperations.md b/doc/deferredFileOperations.md new file mode 100644 index 0000000..93b0229 --- /dev/null +++ b/doc/deferredFileOperations.md @@ -0,0 +1,20 @@ +Deferred file operations +------------------------ +To support self updating services, winsw offers a mechanism to perform file operations before the process you specified in the configuration file gets launched. +This is often necessary because Windows prevents files from overwritten while it's in use. + +To perform file operations, write a text file (in the UTF-8 encoding) at `myapp.copies` + (that is, it's in the same directory as `myapp.xml` and `myapp.exe` but with a different file extension), + and for each operation add one line: + +* To move a file, write a line `src>dst`. If the `dst` file already exists it will be overwritten. + +The success or failure of these operations will be recorded in the event log. + +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. + +I have 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. +Also see `WINSW_EXECUTABLE` environment variable. + +The `` element in the configuration file also provides an useful building block for a self updating services. \ No newline at end of file diff --git a/doc/installation.md b/doc/installation.md new file mode 100644 index 0000000..c70231b --- /dev/null +++ b/doc/installation.md @@ -0,0 +1,77 @@ +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: + +``` + + jenkins + Jenkins + This service runs Jenkins continuous integration system. + + java + -Xrs -Xmx256m -jar "%BASE%\jenkins.war" --httpPort=8080 + rotate + +``` + +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`. + +``` + + + + + + +``` + +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. + +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: + +``` + + + + + +``` + +See [KB 936707](http://support.microsoft.com/kb/936707) for more details. diff --git a/doc/loggingAndErrorReporting.md b/doc/loggingAndErrorReporting.md new file mode 100644 index 0000000..900364e --- /dev/null +++ b/doc/loggingAndErrorReporting.md @@ -0,0 +1,58 @@ + +WinSW Logging and Error Reporting +======= + +### Logging + +Winsw supports several different ways to capture stdout and stderr from the process you launch. + +### Log directory +The `` 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) +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. + + + +### Reset mode +Works like the append mode, except that every time the service starts, the old log files are truncated. + + + +### Ignore mode +Throw away stdout and stderr, and do not produce any log files at all. + + + +### 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 `` element specifies the rotation threshold in KB (defaults to 10MB), and the nested `` element specifies the number of rotated files to keep (defaults to 8.) + +``` + + 10240 + 8 + +``` + +### 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. + +This configuration must accompany a nested `` element, which specifies the timestamp pattern used as the log file name. + +``` + + yyyyMMdd + +``` + +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`. + + + +### Error reporting + +Winsw uses WMI underneath, and as such it uses its error code as the exit code. +See the MSDN article [Create method of the Win32_Service class](http://msdn.microsoft.com/en-us/library/aa389390(VS.85).aspx) for the complete list of exit code. + +When winsw is running as a service, more detailed error information is reported to the Windows event log. \ No newline at end of file diff --git a/doc/selfRestartingService.md b/doc/selfRestartingService.md new file mode 100644 index 0000000..f6d774c --- /dev/null +++ b/doc/selfRestartingService.md @@ -0,0 +1,16 @@ +Self-restarting Windows services +======= + +### Restarting 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. +To restart the service from within, execute `%WINSW_EXECUTABLE% restart!`. +Note that you are invoking `restart!` command, not `restart` command. +This hidden command is a flavor of the `restart` operation, + where winsw creates another winsw process in a separate process group, + and restarts the service from there. + +This additional indirection is necessary because Windows Service Control Manager (SCM) will kill child processes recursively when it stops a service. +SCM doesn't provide the restart operation as an atomic operation either, so winsw implements restart by a sequence of stop and start. +The 2nd winsw process in a separate process group ensures that winsw can survive this massacre to execute the start call. diff --git a/doc/xmlConfigFile.md b/doc/xmlConfigFile.md new file mode 100644 index 0000000..533e9c9 --- /dev/null +++ b/doc/xmlConfigFile.md @@ -0,0 +1,223 @@ +Configuration File Syntax +------------------------- + +This page describes the configuration file, which controls the behavior of the Jenkins service. + +## File structure + +The root element of this XML file must be ``, and it supports the following child element. + +Example: + +``` + + jenkins + Jenkins + This service runs Jenkins continuous integration system. + + java + -Xrs -Xmx256m -jar "%BASE%\jenkins.war" --httpPort=8080 + rotate + +``` + +## Environment Variable Expansion in Configuration File + +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. +If an undefined environment variable is referenced, no substitution occurs. + +## Configuration entries + +### id +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 (while I haven't verified this) this must consist entirely out of alpha-numeric characters. + +### name +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 +Long human-readable description of the service. +This gets displayed in Windows service manager when the service is selected. + +### executable +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.) + +### startmode - Optional Element +This element specifies the start mode of the Windows service. +It can be one of the following values: Boot, System, Automatic, or Manual. +See [MSDN](https://msdn.microsoft.com/en-us/library/aa384896%28v=vs.85%29.aspx) for details. +The default value is `Automatic`. + +### depend +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. + +Multiple elements can be used to specify multiple dependencies. + +``` + Eventlog + W32Time +``` + +### logging + + +Optionally set a different logging directory with `` and startup ``: reset (clear log), roll (move to \*.old) or append (default). + +### argument +This element specifies the arguments to be passed to the executable. +Winsw will quote each argument if necessary, so do not put quotes in `` to avoid double quotation. + +``` + arg1 + arg2 + arg3 +``` + +For backward compatibility, `` element can be used instead to specify the whole command line in a single element. + +### stopargument/stopexecutable +When the service is requested to stop, winsw simply calls [TerminateProcess function](http://msdn.microsoft.com/en-us/library/windows/desktop/ms686714(v=vs.85).aspx ) API to kill the service instantly. +However, if `` elements are present, winsw will instead launch another process of `` (or `` if that's specified) with the `` arguments, and expects that to initiate the graceful shutdown of the service process. + +Winsw will then wait for the two processes to exit on its own, before reporting back to Windows that the service has terminated. + +When you use the ``, you must use `` instead of ``. See the complete example below: + +``` + catalina.sh + jpda + run + + catalina.sh + stop +``` + +Note that the name of the element is `startargument` and not `startarguments`. +As such, to specify multiple arguments, you'll specify multiple elements. + +### stoptimeout +When the service is requested to stop, winsw first attempts to [GenerateConsoleCtrlEvent function](http://msdn.microsoft.com/en-us/library/windows/desktop/ms683155(v=vs.85).aspx) (similar to Ctrl+C), + then wait for up to 15 seconds for the process to exit by itself gracefully. +A process failing to do that (or if the process does not have a console), + then winsw resorts to calling [TerminateProcess function](http://msdn.microsoft.com/en-us/library/windows/desktop/ms686714(v=vs.85).aspx ) API to kill the service instantly. + +This optional element allows you to change this "15 seconds" value, so that you can control how long winsw gives the service to shut itself down. +See `` below for how to specify time duration: + +``` + 10sec +``` + +### env +This optional element can be specified multiple times if necessary to specify environment variables to be set for the child process. The syntax is: + +``` + +``` + +### 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: + +``` + +``` + +Note that since the introduction UAC (Windows Vista and onward), services are no longer really allowed to interact with the desktop. +In those OSes, all that this does is to allow the user to switch to a separate window station to interact with the service. + +### beeponshutdown +This optional element is to emit [simple tone](http://msdn.microsoft.com/en-us/library/ms679277%28VS.85%29.aspx) when the service shuts down. +This feature should be used only for debugging, as some operating systems and hardware do not support this functionality. + +### download +This optional element can be specified multiple times to have the service wrapper retrieve resources from URL and place it locally as a file. +This operation runs when the service is started, before the application specified by `` is launched. + +``` + +``` + +This is another useful building block for developing a self-updating service. + +### log +See the "Logging" section above for more details. + +### onfailure +This optional repeatable element controls the behaviour when the process launched by winsw fails (i.e., exits with non-zero exit code). + +``` + + + +``` + +For example, the above configuration causes the service to restart in 10 seconds after the first failure, restart in 20 seconds after the second failure, then Windows will reboot if the service fails one more time. + +Each element contains a mandatory `action` attribute, which controls what Windows SCM will do, and optional `delay` attribute, which controls the delay until the action is taken. +The legal values for action are: + +* `restart`: restart the service +* `reboot`: reboot Windows +* `none`: do nothing and leave the service stopped + +The possible suffix for the delay attribute is sec/secs/min/mins/hour/hours/day/days. If missing, the delay attribute defaults to 0. + +If the service keeps failing and it goes beyond the number of `` configured, the last action will be repeated. +Therefore, if you just want to always restart the service automatically, simply specify one `` element like this: + + + +### resetfailure +This optional element controls the timing in which Windows SCM resets the failure count. +For example, if you specify `1 hour` and your service continues to run longer than one hour, then the failure count is reset to zero. +This affects the behaviour of the failure actions (see `` above). + +In other words, this is the duration in which you consider the service has been running successfully. +Defaults to 1 day. + +### Service account +It is possible to specify the useraccount (and password) that the service will run as. To do this, specify a `` element like this: + +``` + + YOURDOMAIN + useraccount + Pa55w0rd + true + +``` + +The `` is optional. +If set to `true`, will automatically set the "Allow Log On As A Service" right to the listed account. + +### Working directory +Some services need to run with a working directory specified. +To do this, specify a `` element like this: + + C:\application + +### priority +Optionally specify the scheduling priority of the service process (equivalent of Unix nice) +Possible values are `idle`, `belownormal`, `normal`, `abovenormal`, `high`, `realtime` (case insensitive.) + + idle + +Specifying a priority higher than normal has unintended consequences. +See the MSDN article [ProcessPriorityClass Enumeration](http://msdn.microsoft.com/en-us/library/system.diagnostics.processpriorityclass(v=vs.110).aspx) for details. +This feature is intended primarily to launch a process in a lower priority so as not to interfere with the computer's interactive usage. + +###stopparentprocessfirst +Optionally specify the order of service shutdown. +If `true`, the parent process is shutdown first. +This is useful when the main process is a console, which can respond to Ctrl+C command and will gracefully shutdown child processes. + +``` +true +``` \ No newline at end of file From 26a25c72a162207b71ccf8fee2a69e4246ccf311 Mon Sep 17 00:00:00 2001 From: Oleg Nenashev Date: Fri, 25 Nov 2016 15:34:50 +0300 Subject: [PATCH 04/15] Docs: Update WinSW 1/2 in README --- README.md | 25 ++++++++++++++++--------- 1 file changed, 16 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index caf32e1..a8d583f 100644 --- a/README.md +++ b/README.md @@ -40,16 +40,23 @@ Your renamed `winsw.exe` accepts the following commands: * [Self-restarting services](doc/selfRestartingService.md) * [Deferred File Operations](doc/deferredFileOperations.md) -### Project status +### Release lines -* WinSW 1.x - Maintenance only - * [winsw-1.17](https://github.com/kohsuke/winsw/milestones/winsw-1.17) fixes the most of active issues - * [winsw-1.17-beta.2](https://github.com/kohsuke/winsw/releases/tag/1.17-beta.2) is available for the evaluation - * New versions may be released on-demand - * All new fixes will be ported to WinSW-2.x -* WinSW 2.x - Active development, no stable releases available - * [winsw-2.0](https://github.com/kohsuke/winsw/milestones/winsw-2.0) - Current development branch - * API stability is not guaranteed till the first release, the project structure is in flux +#### WinSW 2.x + +This is a new release line under active development. +API stability is not guaranteed till the first release, the project structure is in flux. + +Major changes since 1.x: +* Rework of the project structure +* Better logging +* Internal plugin engine, which allows extending the WinSW behavior + +#### WinSW 1.x + +This is an old baseline of WinSW. +Currently it is in the maintenance-only state. +New versions with fixes may be released on-demand. ### Build Environment From 1bb286cc4cbe80f7d2d9fffa0251fab748a50489 Mon Sep 17 00:00:00 2001 From: Oleg Nenashev Date: Fri, 25 Nov 2016 23:56:39 +0300 Subject: [PATCH 05/15] Docs: Fix links --- README.md | 17 +++++++++++++---- doc/loggingAndErrorReporting.md | 4 ++-- doc/xmlConfigFile.md | 6 +++--- 3 files changed, 18 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index a8d583f..b39d6b9 100644 --- a/README.md +++ b/README.md @@ -19,10 +19,19 @@ Unix systems have their own conventions for daemons, so a good behaving Unix dae ### Download [Binaries are available here](http://repo.jenkins-ci.org/releases/com/sun/winsw/winsw/) -### Available commands -Your renamed `winsw.exe` accepts the following commands: +### Description -* `install` to install the service to Windows Service Controller +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`. + +WinSW is being managed by configuration files. + +* + +Your renamed `winsw.exe` binary 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). * `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. @@ -31,7 +40,7 @@ Your renamed `winsw.exe` accepts the following commands: ### Documentation -* [Installation Guide](doc/protocols.md) - Describes the installation process for different systems and .NET versions +* [Installation Guide](doc/installation.md) - Describes the installation process for different systems and .NET versions * Configuration: * [Main XML Configuration file](doc/xmlConfigFile.md) * [Configuration File](doc/xmlConfigFile.md) diff --git a/doc/loggingAndErrorReporting.md b/doc/loggingAndErrorReporting.md index 900364e..d6b7b92 100644 --- a/doc/loggingAndErrorReporting.md +++ b/doc/loggingAndErrorReporting.md @@ -53,6 +53,6 @@ For example, in the above example, the log of Jan 1, 2013 gets written to `myapp ### Error reporting Winsw uses WMI underneath, and as such it uses its error code as the exit code. -See the MSDN article [Create method of the Win32_Service class](http://msdn.microsoft.com/en-us/library/aa389390(VS.85).aspx) for the complete list of exit code. +See the MSDN article [Create method of the Win32_Service class](http://msdn.microsoft.com/en-us/library/aa389390%28VS.85%29.aspx) for the complete list of exit code. -When winsw is running as a service, more detailed error information is reported to the Windows event log. \ No newline at end of file +When winsw is running as a service, more detailed error information is reported to the Windows event log. diff --git a/doc/xmlConfigFile.md b/doc/xmlConfigFile.md index 533e9c9..e349269 100644 --- a/doc/xmlConfigFile.md +++ b/doc/xmlConfigFile.md @@ -102,10 +102,10 @@ Note that the name of the element is `startargument` and not `startarguments`. As such, to specify multiple arguments, you'll specify multiple elements. ### stoptimeout -When the service is requested to stop, winsw first attempts to [GenerateConsoleCtrlEvent function](http://msdn.microsoft.com/en-us/library/windows/desktop/ms683155(v=vs.85).aspx) (similar to Ctrl+C), +When the service is requested to stop, winsw first attempts to [GenerateConsoleCtrlEvent function](http://msdn.microsoft.com/en-us/library/windows/desktop/ms683155%28v=vs.85%29.aspx) (similar to Ctrl+C), then wait for up to 15 seconds for the process to exit by itself gracefully. A process failing to do that (or if the process does not have a console), - then winsw resorts to calling [TerminateProcess function](http://msdn.microsoft.com/en-us/library/windows/desktop/ms686714(v=vs.85).aspx ) API to kill the service instantly. + then winsw resorts to calling [TerminateProcess function](http://msdn.microsoft.com/en-us/library/windows/desktop/ms686714%28v=vs.85%29.aspx ) API to kill the service instantly. This optional element allows you to change this "15 seconds" value, so that you can control how long winsw gives the service to shut itself down. See `` below for how to specify time duration: @@ -210,7 +210,7 @@ Possible values are `idle`, `belownormal`, `normal`, `abovenormal`, `high`, `rea idle Specifying a priority higher than normal has unintended consequences. -See the MSDN article [ProcessPriorityClass Enumeration](http://msdn.microsoft.com/en-us/library/system.diagnostics.processpriorityclass(v=vs.110).aspx) for details. +See the MSDN article [ProcessPriorityClass Enumeration](http://msdn.microsoft.com/en-us/library/system.diagnostics.processpriorityclass%28v=vs.110%29.aspx) for details. This feature is intended primarily to launch a process in a lower priority so as not to interfere with the computer's interactive usage. ###stopparentprocessfirst From b16368b8aaf6e3f659c91280c421f8575fedc867 Mon Sep 17 00:00:00 2001 From: Oleg Nenashev Date: Sat, 26 Nov 2016 00:00:30 +0300 Subject: [PATCH 06/15] Docs: Add changelog --- CHANGELOG.md | 50 ++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 1 + 2 files changed, 51 insertions(+) create mode 100644 CHANGELOG.md diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..5c9dc2e --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,50 @@ +Release Notes +==== + +Below you can release notes for the trunk version of WinSW. + +##### 2.0 + +Release date: Coming Soon + +Improvements: +* Introduce a concept of WinSW extensions, which allow extending the wrapper's behavior +([PR #42](https://github.com/kohsuke/winsw/pull/42)). + * Right now the extensions are not guaranteed to be binary compatible + * Engine does not support their inclusion from external DLLs (but you can repackage the executable if you want to extend WinSW) +* `SharedDirectoriesMapper` extension for mapping shared directories when the Windows service starts up +([PR #42](https://github.com/kohsuke/winsw/pull/42)). +* Migrate event logging handlers to log4j +([PR #73](https://github.com/kohsuke/winsw/pull/73)). + +##### 1.19.1 + +Release date: Nov 05, 2016 + +Fixed issues: + +* Fix the version number in the executable file metadata and CLI + +##### 1.19 + +Release date: Aug 02, 2016 + +No functional changes. + +##### 1.18 + +Fixed issues: Aug 23, 2015 + +* [Issue #91](https://github.com/kohsuke/winsw/issues/91) - `%BASE%` contained the executable path instead of the directory path (regression in `1.17`) + + +##### 1.17 + +Release date: Mar 29, 2015 + +Changes: See the [winsw-1.17 milestone](https://github.com/kohsuke/winsw/milestone/1). + +##### Previous versions + +WinSW versions older than `1.17` have no explicit changelog. +If you need such info, see the [commit history](https://github.com/kohsuke/winsw/commits/master). \ No newline at end of file diff --git a/README.md b/README.md index b39d6b9..43e746f 100644 --- a/README.md +++ b/README.md @@ -41,6 +41,7 @@ Your renamed `winsw.exe` binary accepts the following commands: ### Documentation * [Installation Guide](doc/installation.md) - Describes the installation process for different systems and .NET versions +* [Release notes](CHANGELOG.md) * Configuration: * [Main XML Configuration file](doc/xmlConfigFile.md) * [Configuration File](doc/xmlConfigFile.md) From f8a6b32f82ea343f47aad88d21d824ae6cfc2128 Mon Sep 17 00:00:00 2001 From: Oleg Nenashev Date: Sat, 26 Nov 2016 01:05:05 +0300 Subject: [PATCH 07/15] Docs: Integrate documentation from Wiki (solves #132) --- doc/deferredFileOperations.md | 3 +- doc/installation.md | 56 ++++++++++++++++++++++++++++------- doc/xmlConfigFile.md | 4 +++ 3 files changed, 52 insertions(+), 11 deletions(-) diff --git a/doc/deferredFileOperations.md b/doc/deferredFileOperations.md index 93b0229..40caed5 100644 --- a/doc/deferredFileOperations.md +++ b/doc/deferredFileOperations.md @@ -1,5 +1,6 @@ Deferred file operations ------------------------- +==== + To support self updating services, winsw offers a mechanism to perform file operations before the process you specified in the configuration file gets launched. This is often necessary because Windows prevents files from overwritten while it's in use. diff --git a/doc/installation.md b/doc/installation.md index c70231b..73ca97a 100644 --- a/doc/installation.md +++ b/doc/installation.md @@ -3,7 +3,25 @@ WinSW Installation Guide This page provides WinSW installation guidelines for different cases. -### Basic setup +### Installation steps + +In order to setup WinSW, you commonly need to perform the following steps: + +0. Take `winsw.exe` from the distribution, and rename it to your taste (such as `myapp.exe`) +0. Write `myapp.xml `(see [XML Config File specification](xmlConfigFile.md) for more details) +0. Place those two files side by side, because that's how WinSW discovers its configuration. +0. Run `myapp.exe install ` in order to install the service wrapper. +0. Optional - Perform additional configuration in the Windows Service Manager. +0. Optional - Perform extra configurations if required (guidelines are available below). + * Declare that the executable is compatible with .NET 4 or above + * Enable the WinSW offline mode +0. Run the service from the Windows Service Manager. + +There are some details for each step available below. + +### Installation step details + +#### 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: @@ -20,22 +38,40 @@ The example below is a primitive example being used in the Jenkins project: ``` -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. +The full specification of the configuration file is available [here](xmlConfigFile.md). + +#### Step 4. Service registration + You can then install the service like: ``` - jenkins.exe install + 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. +Possible return error codes are described [here](http://msdn.microsoft.com/en-us/library/aa389390%28VS.85%29.aspx). +Beyond these error codes, all the non-zero exit code should be assumed as a failure. -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. +#### Step 5. 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. + +In particular, the following option can be set up: + +* Service automatic startup on the Windows startup +* User or system account, under which the service runs +* Recovery options (how Windows recovers the service if it dies due to whatever reason) + +In addition to the service manager, it is possible to make some additional configurations in the `Windows Registry Editor`. + +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. -### Making WinSW compatible with .NET runtime 4.0+ +### Extra configuration options + +#### 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. @@ -57,7 +93,7 @@ See [this post](http://www.davidmoore.info/2010/12/17/running-net-2-runtime-appl To our knowledge, 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 (see [more discussions](http://msdn.microsoft.com/en-us/library/bb629393.aspx)). diff --git a/doc/xmlConfigFile.md b/doc/xmlConfigFile.md index e349269..593ea81 100644 --- a/doc/xmlConfigFile.md +++ b/doc/xmlConfigFile.md @@ -27,6 +27,10 @@ Configuration XML files can include environment variable expansions of the form Such occurrences, if found, will be automatically replaced by the actual values of the variables. If an undefined environment variable is referenced, no substitution occurs. +Also, the service wrapper sets the environment variable `BASE` by itself, which points to a directory that contains the renamed `winsw.exe`. +This is useful to refer to other files in the same directory. +Since this is an environment variable by itself, this value can be also accessed from the child process launched from the service wrapper. + ## Configuration entries ### id From 4ec9984c1f7ea026e41ad822e8a40b6e695ba60b Mon Sep 17 00:00:00 2001 From: Oleg Nenashev Date: Sat, 26 Nov 2016 01:10:12 +0300 Subject: [PATCH 08/15] Document the "myapp.exe install /p" call --- doc/installation.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/doc/installation.md b/doc/installation.md index 73ca97a..a67a765 100644 --- a/doc/installation.md +++ b/doc/installation.md @@ -45,13 +45,16 @@ The full specification of the configuration file is available [here](xmlConfigFi You can then install the service like: ``` - jenkins.exe install + myapp.exe install ``` ... and you can use the exit code from these processes to determine whether the operation was successful. Possible return error codes are described [here](http://msdn.microsoft.com/en-us/library/aa389390%28VS.85%29.aspx). Beyond these error codes, all the non-zero exit code should be assumed as a failure. +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 5. Windows Service Manager Once the service is installed, you can start it from Windows Service Manager. From b60756b8c578d7cb1d542aa14fa1a6212b0cb94d Mon Sep 17 00:00:00 2001 From: Oleg Nenashev Date: Sat, 26 Nov 2016 01:19:05 +0300 Subject: [PATCH 09/15] Make the document less personalized --- README.md | 11 ++++++----- doc/deferredFileOperations.md | 3 +-- doc/installation.md | 5 ++--- doc/xmlConfigFile.md | 7 +++++-- 4 files changed, 14 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index 43e746f..0b7cae7 100644 --- a/README.md +++ b/README.md @@ -2,18 +2,19 @@ winsw: Windows service wrapper in less restrictive license ========================= ### Why? - -Now, I think the first question that people would ask is, why another, when there's [Java Service Wrapper project](http://wrapper.tanukisoftware.org/doc/english/download.jsp) already available. + +Here is a cite from [Kohsuke Kawaguchi](https://github.com/kohsuke/), who is the original author of this project: + +> Now, I think the first question that people would ask is, why another, when there's [Java Service Wrapper project](http://wrapper.tanukisoftware.org/doc/english/download.jsp) already available. The main reason for writing my own was the license — Java Service Wrapper project is in GPL (so that they can sell their commercial version in a different license), and that made it difficult for [Jenkins](http://jenkins-ci.org/) (which is under the MIT license) to use it. -Functionality-wise, there's really not much that's worth noting; the problem of wrapping a process as a Windows service is so well defined that there aren't really any room for substantial innovation. +> Functionality-wise, there's really not much that's worth noting; the problem of wrapping a process as a Windows service is so well defined that there aren't really any room for substantial innovation. You basically write a configuration file specifying how you'd like your process to be launched, and we provide programmatic means to install/uninstall/start/stop services. Another notable difference is that winsw can host any executable, whereas Java Service Wrapper can only host Java apps. - Whether you like this or not depends on your taste, so I wouldn't claim mine is better. It's just different. -As the name implies, this is for Windows only. +> As the name implies, this is for Windows only. Unix systems have their own conventions for daemons, so a good behaving Unix daemon should just be using `launchd/upstart/SMF/etc`, instead of custom service wrapper. ### Download diff --git a/doc/deferredFileOperations.md b/doc/deferredFileOperations.md index 40caed5..a876100 100644 --- a/doc/deferredFileOperations.md +++ b/doc/deferredFileOperations.md @@ -13,8 +13,7 @@ To perform file operations, write a text file (in the UTF-8 encoding) at `myapp. The success or failure of these operations will be recorded in the event log. 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. - -I have 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. +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. Also see `WINSW_EXECUTABLE` environment variable. diff --git a/doc/installation.md b/doc/installation.md index a67a765..c2dfc46 100644 --- a/doc/installation.md +++ b/doc/installation.md @@ -91,10 +91,9 @@ One way to deal with this is to ensure that `.NET 2.0` runtime is installed thro ``` -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. +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 (e.g. `myapp.exe`). See [this post](http://www.davidmoore.info/2010/12/17/running-net-2-runtime-applications-under-the-net-4-runtime/) for more about this. - -To our knowledge, none of the other flags are needed. +None of the other flags are needed. #### WinSW Offline mode and Authenticode diff --git a/doc/xmlConfigFile.md b/doc/xmlConfigFile.md index 593ea81..43033c9 100644 --- a/doc/xmlConfigFile.md +++ b/doc/xmlConfigFile.md @@ -35,9 +35,8 @@ Since this is an environment variable by itself, this value can be also accessed ### id 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 (while I haven't verified this) this must consist entirely out of alpha-numeric characters. + and it should consist entirely out of alpha-numeric characters. ### name Short display name of the service, which can contain spaces and other characters. @@ -205,13 +204,17 @@ If set to `true`, will automatically set the "Allow Log On As A Service" right t Some services need to run with a working directory specified. To do this, specify a `` element like this: +``` C:\application +``` ### priority Optionally specify the scheduling priority of the service process (equivalent of Unix nice) Possible values are `idle`, `belownormal`, `normal`, `abovenormal`, `high`, `realtime` (case insensitive.) +``` idle +``` Specifying a priority higher than normal has unintended consequences. See the MSDN article [ProcessPriorityClass Enumeration](http://msdn.microsoft.com/en-us/library/system.diagnostics.processpriorityclass%28v=vs.110%29.aspx) for details. From 7c3bd2d40bd8774ac0be0c40162dc2df4e9d9c71 Mon Sep 17 00:00:00 2001 From: Oleg Nenashev Date: Sat, 26 Nov 2016 01:26:12 +0300 Subject: [PATCH 10/15] Update the readme file --- README.md | 24 +++++++++++++----------- 1 file changed, 13 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index 0b7cae7..1c3a96f 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,16 @@ winsw: Windows service wrapper in less restrictive license ========================= +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`. + +### Download +Right now the project uses [Jenkins](https://jenkins.io/index.html) Maven repository as a main storage of release files. +Binaries are available [here](http://repo.jenkins-ci.org/releases/com/sun/winsw/winsw/). + +Some releases (e.g. alpha- and beta-versions) can be also downloaded from the project's GitHub page. +This source of releases is not an **official one**. + ### Why? Here is a cite from [Kohsuke Kawaguchi](https://github.com/kohsuke/), who is the original author of this project: @@ -17,19 +27,11 @@ It's just different. > As the name implies, this is for Windows only. Unix systems have their own conventions for daemons, so a good behaving Unix daemon should just be using `launchd/upstart/SMF/etc`, instead of custom service wrapper. -### Download -[Binaries are available here](http://repo.jenkins-ci.org/releases/com/sun/winsw/winsw/) +### Usage -### Description +WinSW is being managed by configuration files: [Main XML Configuration file](doc/xmlConfigFile.md) and [EXE .config file](TODO). -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`. - -WinSW is being managed by configuration files. - -* - -Your renamed `winsw.exe` binary accepts the following commands: +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). From 33efbdd7dde2402098b55db15c16a40dab5b66e6 Mon Sep 17 00:00:00 2001 From: Oleg Nenashev Date: Sat, 26 Nov 2016 01:28:42 +0300 Subject: [PATCH 11/15] Docs: Decouple the project manifest to a standalone page --- MANIFEST.md | 16 ++++++++++++++++ README.md | 20 ++++---------------- 2 files changed, 20 insertions(+), 16 deletions(-) create mode 100644 MANIFEST.md diff --git a/MANIFEST.md b/MANIFEST.md new file mode 100644 index 0000000..3660ed4 --- /dev/null +++ b/MANIFEST.md @@ -0,0 +1,16 @@ +Project manifest +=== + +Here is a cite from [Kohsuke Kawaguchi](https://github.com/kohsuke/), who is the original author of this project: + +> Now, I think the first question that people would ask is, why another, when there's [Java Service Wrapper project](http://wrapper.tanukisoftware.org/doc/english/download.jsp) already available. +The main reason for writing my own was the license — Java Service Wrapper project is in GPL (so that they can sell their commercial version in a different license), and that made it difficult for [Jenkins](http://jenkins-ci.org/) (which is under the MIT license) to use it. + +> Functionality-wise, there's really not much that's worth noting; the problem of wrapping a process as a Windows service is so well defined that there aren't really any room for substantial innovation. +You basically write a configuration file specifying how you'd like your process to be launched, and we provide programmatic means to install/uninstall/start/stop services. +Another notable difference is that winsw can host any executable, whereas Java Service Wrapper can only host Java apps. +Whether you like this or not depends on your taste, so I wouldn't claim mine is better. +It's just different. + +> As the name implies, this is for Windows only. +Unix systems have their own conventions for daemons, so a good behaving Unix daemon should just be using `launchd/upstart/SMF/etc`, instead of custom service wrapper. \ No newline at end of file diff --git a/README.md b/README.md index 1c3a96f..6e5b8e3 100644 --- a/README.md +++ b/README.md @@ -4,6 +4,10 @@ winsw: Windows service wrapper in less restrictive license 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? + +See the [project manifest](MANIFEST.md). + ### Download Right now the project uses [Jenkins](https://jenkins.io/index.html) Maven repository as a main storage of release files. Binaries are available [here](http://repo.jenkins-ci.org/releases/com/sun/winsw/winsw/). @@ -11,22 +15,6 @@ Binaries are available [here](http://repo.jenkins-ci.org/releases/com/sun/winsw/ Some releases (e.g. alpha- and beta-versions) can be also downloaded from the project's GitHub page. This source of releases is not an **official one**. -### Why? - -Here is a cite from [Kohsuke Kawaguchi](https://github.com/kohsuke/), who is the original author of this project: - -> Now, I think the first question that people would ask is, why another, when there's [Java Service Wrapper project](http://wrapper.tanukisoftware.org/doc/english/download.jsp) already available. -The main reason for writing my own was the license — Java Service Wrapper project is in GPL (so that they can sell their commercial version in a different license), and that made it difficult for [Jenkins](http://jenkins-ci.org/) (which is under the MIT license) to use it. - -> Functionality-wise, there's really not much that's worth noting; the problem of wrapping a process as a Windows service is so well defined that there aren't really any room for substantial innovation. -You basically write a configuration file specifying how you'd like your process to be launched, and we provide programmatic means to install/uninstall/start/stop services. -Another notable difference is that winsw can host any executable, whereas Java Service Wrapper can only host Java apps. -Whether you like this or not depends on your taste, so I wouldn't claim mine is better. -It's just different. - -> As the name implies, this is for Windows only. -Unix systems have their own conventions for daemons, so a good behaving Unix daemon should just be using `launchd/upstart/SMF/etc`, instead of custom service wrapper. - ### Usage WinSW is being managed by configuration files: [Main XML Configuration file](doc/xmlConfigFile.md) and [EXE .config file](TODO). From 38ccac88ca0d6502e7dc730e3e6e41bc461cf724 Mon Sep 17 00:00:00 2001 From: Oleg Nenashev Date: Sat, 26 Nov 2016 01:36:39 +0300 Subject: [PATCH 12/15] Add a simple documentation stub for the EXE Config File --- README.md | 4 ++-- doc/exeConfigFile.md | 10 ++++++++++ doc/xmlConfigFile.md | 4 ++-- 3 files changed, 14 insertions(+), 4 deletions(-) create mode 100644 doc/exeConfigFile.md diff --git a/README.md b/README.md index 6e5b8e3..ae9c455 100644 --- a/README.md +++ b/README.md @@ -17,7 +17,7 @@ This source of releases is not an **official one**. ### Usage -WinSW is being managed by configuration files: [Main XML Configuration file](doc/xmlConfigFile.md) and [EXE .config file](TODO). +WinSW is being managed by configuration files: [Main XML Configuration file](doc/xmlConfigFile.md) and [EXE Config file](doc/exeConfigFile.md). Your renamed `winsw.exe` binary also accepts the following commands: @@ -35,7 +35,7 @@ Your renamed `winsw.exe` binary also accepts the following commands: * [Release notes](CHANGELOG.md) * Configuration: * [Main XML Configuration file](doc/xmlConfigFile.md) - * [Configuration File](doc/xmlConfigFile.md) + * [EXE Configuration File](doc/exeConfigFile.md) * [Logging and Error Reporting](doc/loggingAndErrorReporting.md) * Use-cases: * [Self-restarting services](doc/selfRestartingService.md) diff --git a/doc/exeConfigFile.md b/doc/exeConfigFile.md new file mode 100644 index 0000000..fdd7c92 --- /dev/null +++ b/doc/exeConfigFile.md @@ -0,0 +1,10 @@ +WinSW 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: +* 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. \ No newline at end of file diff --git a/doc/xmlConfigFile.md b/doc/xmlConfigFile.md index 43033c9..c1943e2 100644 --- a/doc/xmlConfigFile.md +++ b/doc/xmlConfigFile.md @@ -1,5 +1,5 @@ -Configuration File Syntax -------------------------- +WinSW XML Configuration File +==== This page describes the configuration file, which controls the behavior of the Jenkins service. From dc9378d9e58aebed1bd385f002b46d2649225a15 Mon Sep 17 00:00:00 2001 From: Oleg Nenashev Date: Sat, 26 Nov 2016 01:40:02 +0300 Subject: [PATCH 13/15] Docs: Cleanup leftover TODOs --- doc/installation.md | 3 +-- doc/xmlConfigFile.md | 3 ++- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/installation.md b/doc/installation.md index c2dfc46..1510718 100644 --- a/doc/installation.md +++ b/doc/installation.md @@ -76,8 +76,7 @@ Once the start button is clicked, Windows will start `myapp.exe`, #### 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. +Modern versions of Windows (e.g. Windows Server 2012 or Windows 10) 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`. diff --git a/doc/xmlConfigFile.md b/doc/xmlConfigFile.md index c1943e2..9c6abb3 100644 --- a/doc/xmlConfigFile.md +++ b/doc/xmlConfigFile.md @@ -69,9 +69,10 @@ Multiple elements can be used to specify multiple dependencies. ### logging - Optionally set a different logging directory with `` and startup ``: reset (clear log), roll (move to \*.old) or append (default). +See the [Logging and Error reporting page](loggingAndErrorReporting.md) for more info. + ### argument This element specifies the arguments to be passed to the executable. Winsw will quote each argument if necessary, so do not put quotes in `` to avoid double quotation. From e69957824b5af9eba1fc945b724753915dc94e58 Mon Sep 17 00:00:00 2001 From: Oleg Nenashev Date: Sat, 26 Nov 2016 01:41:07 +0300 Subject: [PATCH 14/15] Docs: Update LICENCE.txt, mention other contributors --- LICENSE.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/LICENSE.txt b/LICENSE.txt index 51402f1..a2a1fdd 100644 --- a/LICENSE.txt +++ b/LICENSE.txt @@ -1,4 +1,4 @@ - Copyright (c) 2010 Kohsuke Kawaguchi, Sun Microsystems, Inc., CloudBees, Inc. + Copyright (c) 2010-2016 Kohsuke Kawaguchi, Sun Microsystems, Inc., CloudBees, Inc., Oleg Nenashev and other contributors Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation From 73367e61f06cb55ad17f06b951e932011c674380 Mon Sep 17 00:00:00 2001 From: Oleg Nenashev Date: Mon, 28 Nov 2016 21:50:10 +0100 Subject: [PATCH 15/15] Docs: Address comments from @jtnord --- CHANGELOG.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 5c9dc2e..5df6b1e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,20 +1,20 @@ Release Notes ==== -Below you can release notes for the trunk version of WinSW. +Below you can find release notes for the trunk version of WinSW. ##### 2.0 Release date: Coming Soon Improvements: -* Introduce a concept of WinSW extensions, which allow extending the wrapper's behavior +* Introduced a concept of WinSW extensions, which allows extending the wrapper's behavior ([PR #42](https://github.com/kohsuke/winsw/pull/42)). - * Right now the extensions are not guaranteed to be binary compatible - * Engine does not support their inclusion from external DLLs (but you can repackage the executable if you want to extend WinSW) -* `SharedDirectoriesMapper` extension for mapping shared directories when the Windows service starts up + * The extension binary backward comparability is not guaranteed + * The engine does not support extensions in external DLLs (but you can repackage the executable if you want to extend WinSW) +* `SharedDirectoriesMapper` extension for mapping shared directories when the Windows service starts ([PR #42](https://github.com/kohsuke/winsw/pull/42)). -* Migrate event logging handlers to log4j +* Migrate event logging to log4j ([PR #73](https://github.com/kohsuke/winsw/pull/73)). ##### 1.19.1 @@ -29,7 +29,7 @@ Fixed issues: Release date: Aug 02, 2016 -No functional changes. +* No functional changes. ##### 1.18