The basic syntax for winserv invocation is the following:
One notable exception to this rule is the help subcommand that doesn't need any arguments (and ignores them, if any). Some subcommands (showconfig, status) accept more than one service name.
winserv install service-name service-options program args ...
creates a service that runs command (any executable) when started and stops when the program exits. Command-line parameters for the command may also be specified.
winserv configure service-name service-options program args ...
modifies various parameters for the service in SCM and registry databases. If the program is specified, it is stored in registry as a new program to be started by this winserv-based service.
winserv uninstall service-name
marks a service for deletion. When it is stopped and all its handles are closed, the service is removed from the SCM database.
winserv showconfig service-name1 service-name2 ...
shows the current service's parameters that may be modified with the configure subcommand. Some parameters make sense only for winserv-based services, and they will not be shown for other services (see parameters description below).
winserv stop service-name -nowait
winserv pause service-name -nowait
winserv continue service-name -nowait
winserv usercontrol service-name -code code
These subcommands send control signals to the running service. -nowait option means that the utility shouldn't wait until the service will report an appropriate status for the request (stopped for stop, paused for pause, running for continue).
winserv start service-name args ...
Starts the service using the given command-line arguments. If the service is winserv-based, the arguments are stored in the ServiceArgs environment variable.
winserv restart service-name args ...
Restarts the service, i.e. stops it, waits for it to be stopped, and then starts it with the arguments given.
winserv status service-name1 service-name2 ...
Prints out the current status of the services, one of: RUNNING, STOPPED, PAUSED, START_PENDING, PAUSE_PENDING, CONTINUE_PENDING, STOP_PENDING. The program's output is formatted like this:
You see that the program prints the list of SCM control signals that the service can accept now.
subcommands, you can specify parameters for the newly-created
or configured service. Some of the service options require an argument. Here is the list of supported service options with arguments:
- -displayname user-visible display name of the service
- -description the description of the service, usually one or two sentences
- -binary pathname of winserv.exe, defaults to the invoked instance's pathname
- -ipcmethod ipc method, one of: blind, pipe, stdio or qstdio
- -start start mode, one of auto, demand or disabled
- -errorcontrol error control mode, one of ignore, normal, severe or critical
- -loadordergroup load-order group name. See Platform SDK Documentation for details
- -depends service1,service2... – comma-separated list of other services
- -user the service will log on as this user
- -password the user's password
Winserv will refuse to set binary pathname and some winserv-specific
options for non-winserv
based services. Use -forceforeign
option to suppress this behavior.
Use -expand option to store the application's command-line in registry as a REG_EXPAND_SZ type of value. In this case, all references to environment variables will be auto-expanded before starting the application:
Note that you have to use -expand with %ServiceArgs% to pass the service's command-line parameters as extra arguments.
Winserv can communicate with the underlying application or script in three different ways, depending on -ipcmethod
option given to install
subcommands when the service was installed:
It's the simpliest case, when the application is terminated with TerminateProcess if the service is stopped. There is no way for the application to do any cleanup, and it can't write to the event log or accept pause/continue and other signals. This method must be used only for 3rd-party closed-source
applications that don't have any worthy data in memory that must be written on exit.
Winserv forwards the SCM signals in the textual form to the applications's standard input, and the application reports its state on its standard output. The application can use special escape sequences to write to the eventlog with specific level (error, information, success, etc.), to signal its current status (paused, running), to declare what SCM control codes it accepts.
Any plain-text (escapeless) line from stdout is just written to the event log at the information level, and any line from stderr is written at the error level.
This IPC method may be used for closed-source application that doesn't know anything about winserv. In this case you won't be able to terminate the application with SCM control code (winserv stop); it must terminate by itself.
This method is similar to stdio, except that unescaped plain-text
strings aren't forwarded to the event log. It may be useful if the application is too chatty.
This method was designed especially for non-console tclkits
, where we don't have access to normal stdin or stdout, but only to their emulation. The application must open two named pipes on startup:
and use the first one instead of stdout, and the second one instead of stdin. In all other aspects this method is equivalent to stdio.
Don't change the order in which the pipes are opened! If you do it, the communication between winserv and the application can't be established.
If the named pipes are not opened after 30 seconds, winserv will terminate the application.
Remote service management
You can prepend \\Machine\ to the service name, thus specifying that you want to manage a service on a named remote machine. For the subcommands that accept more than one service in their arguments, the machine name may be specified for the first service only
. All other services will be opened on that machine automatically.
When you aren't a domain administrator, it's typical situation when you are able to access remote service control manager, but unable to read remote registry database. Winserv will do the best it can. When you use winserv showconfig to see the service's parameters, most of them will be retrieved from the service control manager, and the warning message will be printed to let you know that the remote registry was inaccessible.