2004-11-07 00:19:47

The basic syntax for winserv invocation is the following: winserv subcommand service-name options [ args ... ]
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:
Service: myservice Status: RUNNING Accepts: STOP
You see that the program prints the list of SCM control signals that the service can accept now.

Service options

Using install and configure 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
-[no]expand
-[non]interactive
-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:
winserv install myappsrv -expand %SystemRoot%\MyApp.exe %ServiceArgs%
Note that you have to use -expand with %ServiceArgs% to pass the service's command-line parameters as extra arguments.

IPC methods

Winserv can communicate with the underlying application or script in three different ways, depending on -ipcmethod option given to install or configure subcommands when the service was installed:

blind

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.

stdio

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.

qstdio

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.

pipe

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:
open \\\\.\\pipe\\winserv.scm.out.$service_name w+ open \\\\.\\pipe\\winserv.scm.in.$service_name w+
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.

2004-11-06 19:42:16

edited by AntonKovalenko

2004-11-06 19:04:14

edited by AntonKovalenko

2004-11-06 18:17:34

edited by AntonKovalenko

2004-11-06 18:17:03

edited by AntonKovalenko

2004-11-06 18:14:07

edited by AntonKovalenko

2004-11-06 18:13:42

edited by AntonKovalenko

2004-11-06 18:07:16

edited by AntonKovalenko

2004-11-06 18:06:57

edited by AntonKovalenko

2004-11-06 18:00:59

edited by AntonKovalenko

2004-11-06 17:45:11

edited by AntonKovalenko

2004-11-06 17:33:39

edited by AntonKovalenko

2004-11-06 17:30:38

edited by AntonKovalenko

2004-11-06 17:30:25

edited by AntonKovalenko

Sw4me - Winserv/CommandLine

2004-11-07 00:19:47

Command-line overview

winserv install service-name service-options program args ...

winserv configure service-name service-options program args ...

winserv uninstall service-name

winserv showconfig service-name1 service-name2 ...

winserv stop service-name -nowait

winserv pause service-name -nowait

winserv continue service-name -nowait

winserv usercontrol service-name -code code

winserv start service-name args ...

winserv restart service-name args ...

winserv status service-name1 service-name2 ...

Service options

IPC methods

blind

stdio

qstdio

pipe

Remote service management

2004-11-06 19:42:16

2004-11-06 19:04:14

2004-11-06 18:17:34

2004-11-06 18:17:03

2004-11-06 18:14:07

2004-11-06 18:13:42

2004-11-06 18:07:16

2004-11-06 18:06:57

2004-11-06 18:00:59

2004-11-06 17:45:11

2004-11-06 17:33:39

2004-11-06 17:30:38

2004-11-06 17:30:25