Windows NT provides support for special programs called services . NT services run in the background, usually without direct user interaction, often started automatically at some point in the boot process. They typically run under a special "system" account which means that they do not need to be associated with a username and password. (This also places some security restrictions on what services can do by default.)

Services are analogous to Unix "daemons," but formalised into the operating system. This formal role of NT services brings some advantages to the system administrator. For example, they can be configured to start automatically at various points in the boot process, or can be controlled - locally or remotely - using NET START, Control Panel Services or programs such as SrvPanel.

The downside of this is that ordinary programs will not run as NT services. A service program needs to establish and maintain contact with the NT Service Control Manager (SCM). This requires special coding endemic to the program: if a service does not maintain contact with the SCM, NT assumes it has failed and shuts it down.

As an alternative to writing special code, the Windows NT Resource Kit provides a utility called SRVANY.EXE . SRVANY.EXE will start an ordinary program in the context of an NT service. However it is pretty limited and does not address some of the constraints of NT Services:

• NT Services run using the default (system) environment and directory. However often it is necessary to run such programs with their own environment values.
• There is no facility to automatically restart services which crash (as per Unix init).
• SRVANY.EXE is crude in its handling of service startup and shutdown. It assumes that the program is running as soon as it starts, and has no way to shut down the program other than by terminating it.

Because of these limitations I wrote two utilities, SVC and SRVSTART. SVC allows you to install, modify or remove Windows NT services. SRVSTART allows you to run executable programs as if they were services.

Between them they give you far greater management and flexibility than is provided by the Windows NT and the NT Resource Kit.

Copyright and Distribution

SVC and SRVSTART are distributed under the terms of the GNU General Public License as published by the Free Software Foundation (675 Mass Ave, Cambridge, MA 02139, USA) They are distributed in the hope that they will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

Effectivity

SRVSTART is a rewrite (in C++) of an earlier version of the program called SYBSTART . The new version contains a number of enhancements and extra features.

SVC.EXE - Windows NT Service Management

Pre-Requisites

• svc.exe - SVC executable
• msvcrt.dll - Microsoft C++ run-time library

Synopsis

Operation

• l - list existing services
• d - display details of a existing service
• i - install a new service
• m - modify an existing service
• r - remove an existing service.

SVC will prompt you for all responses. At any point you can type ? (question mark) for a short explanatory help message.

If you are having trouble running SVC, you can try running svc.exe -d . This prints out internal SVC debug messages as it runs.

If you don't like SVC's command-line interface, I recommend SrvPanel from Ballard Software. This is an easy-to-use GUI utility which allows you to install and modify services, although it doesn't have all the install functionality of SVC. It also has a very nice interface for starting and stopping services individually or in groups.

Restrictions

1. It must be a service on the local machine.
2. It must be of type WIN32_OWN_PROCESS (ie not shared).
3. It must be of start type 'automatic,' 'demand' or 'disabled'.

Warning

Making incorrect changes can render Windows NT unuseable.

If you don't know what you are doing, don't mess about with services!

SRVSTART.EXE - Windows NT Service Execution

Pre-Requisites

• srvstart.exe - SRVSTART executable
• srvstart.dll - SRVSTART library
• logger.dll - logger library
• msvcrt.dll - Microsoft C++ run-time library

Synopsis

• It can be used to run an ordinary command (executable program batch file). In this command mode, SRVSTART can prompt the user for the values of command-line parameters such as passwords.
• It can be used to run an executable program in the context of a Windows NT service (service mode). SRVSTART will itself handle all of the interactions with the NT Service Control Manager (SCM). It is not necessary for the program to include any service management code.

Command Mode

srvstart cmd window_title [ options ... ] program [ program_parameters ... ]

• The cmd keyword tells SRVSTART that this is command mode.
• window_title will be displayed (in most cases) in the window's title bar when the command runs. Enclose it in quotes if it contains spaces.
• program and program_parameters ... define the command to run.
• The options are defined below.

Service Mode

srvstart svc service_name [ options ... ] program [ program_parameters ... ]

• The svc keyword tells SRVSTART that this is service mode.
• service_name is the short (internal) name of the service. (You will have defined this when you installed the service using SVC .)
• program and program_parameters ... define the command to run.
• The options are defined below.

Note

For testing, you can supply the keyword any instead of cmd or svc. This will attempt to run the program as a service (keyword svc) and if this fails run it as a console command (keyword cmd).

Operation

1. If it is running in service mode, it connects to the SCM.
2. It sets %PATH% , %LIB% and any other environment variables which have been defined in its command line or control file.
3. If it is running in command mode, it optionally prompts the user for input in response to supplied prompts.
4. It starts the command which has been supplied to it.
5. If it is running in service mode, it:
   • optionally waits to let the started process initialise
   • notifies the SCM that the service has started
   • waits for requests from the SCM (eg to interrogate or stop the service) and acts on these
   • if a "shutdown" request is received, it shuts down the program, and exits
   • periodically checks the started command to see if it is still running; if it has finished, it notifies the SCM that it has stopped, and exits.

Options

-c controlfile

retrieve SRVSTART options from the file controlfile

-d level

set the SRVSTART debug level: 0 =none, 1 =normal, 2 =verbose

-e var=value

set the environment variable var equal to value before running the program

-h

display help message to stdout and exit

-l libdir

set the value of the %LIB% environment variable to libdir

-o target

define where SRVSTART will write debug messages (- , LOG or pathname)

-p path

set the value of the %PATH% environment variable to path

-q sybase

assign a default %PATH% based on this value of sybase instead of value supplied using -s

-s sybase

set the value of the %SYBASE% environment variable to sybase (equivalent to -eSYBASE=sybase )

-x priority

start the command at the given execution priority (IDLE, NORMAL, HIGH, REAL)

The following SRVSTART options apply to command mode only.

-m

start command in minimised new window

-w

start command in new window

The following SRVSTART options apply to service mode only.

-t seconds

program status check interval in seconds

-y seconds

how long SRVSTART waits before reporting a "started" status to the NT Service Control Manager

Environment Options

If no -p option is given, a default path of the form:

%SYBASE%\install;SYBASE%\bin;%SYBASE%\dll;%SystemRoot%;%SystemRoot%\system32

The -q option assigns a path as above, but using the value supplied to -q , instead of %SYBASE%. For example, -q C:\NEWSYB would assign a path of the form C:\NEWSYB\install;C:\NEWSYB\bin;... etc.

Environment values which contain embedded environment variables will have these substituted, but only if they are already defined. For example:

... -l myvar1=myvalue1 -l myvar2=my_%myvar1%_val ...

... -l myvar2=my_%myvar1%_val -l myvar1=myvalue1 ...

Debugging Options

• -d 0 prevents any output other than error messages.
• -d 1 outputs a few informational messages.
• -d 2 outputs a large number of debug messages.

-o target causes debug messages to be sent to target.

• If target is - (hyphen) messages will go to stdout. This does not apply to service mode (messages will just disappear).
• If target is LOG (uppercase) debug messages will be sent to the Windows NT Event Log.
• Otherwise, target is assumed to be a pathname. Debug messages will be appended to this file.

-h displays help information and exits. (The other srvstart parameters need not be supplied in this case.)

Startup Options

• IDLE to run only when the CPU is otherwise idle
• NORMAL to run at normal priority
• HIGH to run at high priority
• REAL to run at real time priority

In command mode, -w opens a new console window to run the program, and -m opens this window minimised. These options are ignored in service mode.

Service Management Options

In service mode, SRVSTART regularly checks the process it has started to see if it is still running. If it has finished, then SRVSTART reports a "service stopped" status to the Service Control Manager and then exits. The -t seconds option defines how often this check is done (default every second).

Control File

This is a text file with one option per line. Options are grouped in sections, with the section name (which is the window or service name) in square brackets. Options before any section apply to all commands.

All section lines are of the form [service_or_window_name]. All option lines are of the form keyword=value. Blank lines, and comments lines (starting #) are ignored.

For example:

# comment
keyword=value
...

[service_or_window_name_1]
keyword=value
keyword=value
...

[service_or_window_name_2]
keyword=value
...

When a control file is used, the program and program_parameters can be omitted from the command line.

Control File Keywords

debug=level

same as -d level

debug_out=target

same as -o target

env=var=value

same as -e var=value

lib=libdir

same as -l libdir

minimised={y|n}

same as -m

new_window={y|n}

same as -w

path=path

same as -p path

priority=priority

same as -x priority

sybase=sybase

same as -s sybase

sybpath=path

same as -q path

startup_delay=seconds

same as -y seconds

wait_time=seconds

same as -t seconds

The following keywords are used to define SRVSTART commands. Apart from startup they have no command-line equivalents.

startup=program [ program_parameters ...]

This defines the service program command. It replaces the program and program_parameters which are supplied on the SRVSTART command line.

startup_dir=path

This defines the startup directory. It should be a full pathname including drive letter.

wait=program [ program_parameters ... ]

This defines a command that SRVSTART will run after starting the service program (service mode only).

This should wait for the service program to enter a "running" state (eg wait for a database server to complete recovery). It should exit with a status of 0 once the service program is up and running. It should exit with a non-zero status if the service program has failed or is never going to enter a running status. Once this command has exited with a status of 0, SRVSTART considers that the service program is running.

shutdown=program [ program_parameters ... ]

This defines a command to shut down the service program (service mode only). SRVSTART will run this command if it receives a "shutdown" request from the SCM (eg a user runs NET STOP or stops the service using Control Panel | Services).

Note that if the shutdown option is not defined, then SRVSTART will shut down the service program using the Win32 TerminateProcess() API. This is apparently equivalent to a Unix kill -9 and leaves DLLs in an undefined state. I have not to date observed any problems with this.

auto_restart={y|n}
restart_interval=seconds

If auto_restart is set, then SRVSTART will restart the service program if it exits for any reason. (The assumption here is that the service has crashed.) If restart_interval is defined, then before restarting, SRVSTART will wait seconds seconds.

auto_restart does not, of course, restart the service program if it is stopped by request (eg NET STOP or Control Panel|Services).

Command

program and program_parameters may refer to environment variables using the %var% syntax. These will be substituted (not recursively) where encountered, for example %HOME%\bin\mycommand.exe %SYSTEMROOT% .

For command mode, if the -w flag is not supplied, the command can also be a DOS command (eg dir).

Parameters

{prompt}
{prompt:default}

If the user just presses return, then default will be used (if supplied). Either default or prompt can be empty strings.

If prompt or default include a space or other symbol meaningful to the NT "shell", surround them in double-quotes.

If prompt begins with a - (hyphen) then the text entered by the user will not be echoed back to the terminal (for passwords etc).

For example:

send_server.exe -s{server:MYSERV} -u{user name} -p{-password}

server [MYSERV]: enter server name here or press return for MYSERV
user name: no default
password: response will not be echoed to screen

Bugs

SRVSTART does not extensively validate things supplied to it on the command line or in the control file. A bad invocation can sometimes cause it to core dump.

SRVSTART is pretty relaxed in its error-checking of things like new . Failure here should become obvious pretty quickly.

In command mode when the -w flag is not supplied, it would be very useful if SRVSTART changed the window title (so you could see it in the taskbar). I can't work out how to do this.

SRVSTART.DLL - Windows NT Service Support Library

This allows you to write your own NT services, making just a few simple calls to manage the service's interactions with the SCM.

Pre-Requisites

• srvstart.dll - SRVSTART library
• logger.dll - logger library
• msvcrt.dll - Microsoft C++ run-time library

• CmdRunner.h and/or ScmConnector.h - SRVSTART header files
• srvstart.lib - SRVSTART library definitions

Further information on building programs to use the DLL is given below.

Synopsis

• CmdRunner (defined in the header file CmdRunner.h)
• ScmConnector (defined in the header file ScmConnector.h)

Class: CmdRunner

The following examples show how to use CmdRunner to run a command in the same or another process.

1. Create a single object instance of the CmdRunner class.

   #include <CmdRunner.h>
   // typedef enum START_MODES { COMMAND_MODE, SERVICE_MODE, ANY_MODE };
   // CmdRunner(START_MODES mode = COMMAND_MODE,char *nm = NULL) throw (SrvStartException) ;
   
   cmdRunner = new CmdRunner(CmdRunner::COMMAND_MODE,"MY_COMMAND");
   
   

   It is invalid to create more than one CmdRunner object.

2. Define the command to run, with any parameters.

   #include <CmdRunner.h>
   // void setStartupCommand(const char *sc);
   // void addStartupCommandArgument(const char *arg);
   
   cmdRunner->setStartupCommand("D:\bin\mycommand.exe");
   cmdRunner->addStartupCommandArgument("arg1");
   // etc.
   
   

3. (Optional) define any required environment variables.

   #include <CmdRunner.h>
   // void addEnv(const char *nm,const char *val) throw (SrvStartException);
   
   cmdRunner->addEnv("MYVAR","MYVALUE");
   // etc.
   
   

4. (Optional) set any other required attributes of the object.

   #include <CmdRunner.h>
   // void setStartInNewWindow(bool nw);
   // etc.
   
   cmdRunner->setStartInNewWindow(true);
   // etc.
   
   

5. Start.

   #include <CmdRunner.h>
   // void start() throw (SrvStartException);
   
   cmdRunner->start();
   
   

   start() blocks until the command has completed.

Class: ScmConnector

The following examples show how to use ScmConnector in a service program.

1. Early on in your program, create a single object instance of the ScmConnector class.

   #include <ScmConnector.h>
   // ScmConnector(char *svcName,bool allowConnectErrors = false) throw (SrvStartException) ;
   
   scmConnector = new ScmConnector("MY_SERVICE");
   
   

   It is invalid to create more than one ScmConnector object.

2. Install a stop handler. This will be activated by the ScmConnector if the service receives a STOP request from the Service Control Manager. The three ways of doing this are described below.

3. Continue starting your service. Once you have completed all of your startup tasks, notify the ScmConnector object that your service is running.

   #include <ScmConnector.h>
   // void notifyScmStatus(SCM_STATUSES scmStatus,bool ignoreErrors = false) throw (SrvStartException);
   
   scmConnector->notifyScmStatus(ScmConnector::STATUS_RUNNING);
   

4. When (if ever) your service is ready to terminate, notify the ScmConnector object.

   #include <ScmConnector.h>
   
   scmConnector->notifyScmStatus(ScmConnector::STATUS_STOPPING);
   scmConnector->notifyScmStatus(ScmConnector::STATUS_STOPPED);
   
   ExitProcess(...)
   

ScmConnector Stop Handlers

There are three ways to do this.

• Pass the address of a Boolean variable to the ScmConnector . If a STOP request is received, the Scm Connector will set this variable to true.

  #include <ScmConnector.h>
  // void installStopCallback(bool *stopRequestedVar) throw (SrvStartException);
  
  bool stopRequested;
  scmConnector->installStopCallback(&stopRequested);
  // later ...
  if (stopRequested) ...
  
  

  If you select this method, then you will typically poll the variable regularly to see if it has been set to true, and if it has, shut down.

• Pass the address of a Win32 event handle (you must create the event yourself). If a STOP request is received, the ScmConnector will signal this event.

  #include <ScmConnector.h>
  // void installStopCallback(HANDLE *stopRequestedEvent) throw (SrvStartException);
  
  HANDLE stopEvent = CreateEvent(NULL,FALSE,FALSE,NULL);
  scmConnector->installStopCallback(&stopEvent);
  // later ...
  WaitForSingleObject(stopEvent,...
  
  

  If you select this method, you will typically poll the event regularly (or maybe wait on it) to see if it has been signalled, and if it has, shut down.

• Pass the address of a static function. If a STOP request is received, the ScmConnector will invoke this function, passing a supplied pointer (which you supply when you install the callback). Note that the function is invoked asynchronously in a separate thread.

  #include <ScmConnector.h>
  // typedef void STOP_HANDLER_FUNCTION(void*);
  // void installStopCallback(STOP_HANDLER_FUNCTION *stopRequestedFunction, void *genericPointer) throw (SrvStartException);
  
  // define the function
  void stopCallbackFunction(void *genericPointer) { ... }
  
  scmConnector->installStopCallback(&stopCallbackFunction, static_cast<void*>(this));
  

  If you select this method, your passed function must shut down the service itself.

Whichever method you choose, you must ensure that if the callback is activated, your service program will shut itself down.

Timing

To ensure this, you should make sure that you create the ScmConnector object early in your program (preferably right at the start). Once you do this, ScmConnector will make the appropriate status notifications to the Service Control Manager for you.

Furthermore, a service program must respond promptly to requests from the Service Control Manager (specifically, "interrogate" and "stop" requests). ScmConnector handles this for you automatically once it has been instantiated. It runs in its own thread (two threads, actually) and you do not need to take any special actions other than to notify it when your status changes (when you are shutting down).

These constraints aside, there are no restrictions on the time that a service can take to start or stop. However ScmConnector will log an informational message if startup takes more than a minute.

Exception Handling

class::method(parameters...) throw (SrvStarterException);

All exceptions are of class SrvStart::SrvStarterException, defined in SrvStart.h. (SrvStart is the namespace here.) Some of the key public data members of this class include:

SRVSTART_EXCEPTION exceptionId;
char className[SRVSTART_EXCEPTION_STRING_SIZE];
char methodName[SRVSTART_EXCEPTION_STRING_SIZE];
char errorMessage[SRVSTART_EXCEPTION_STRING_SIZE];
char sourceFile[SRVSTART_EXCEPTION_STRING_SIZE];
int lineNumber;

"Any" Mode

When creating your ScmConnector object, set the paramter allowConnectErrors to true. Then check the status of the service.

#include <ScmConnector.h>
// typedef enum SCM_STATUSES { STATUS_INITIALISING,STATUS_STARTING,
// STATUS_RUNNING,STATUS_STOPPING,STATUS_STOPPED,
// STATUS_MUST_START_AS_CONSOLE,STATUS_FAILED };
// SCM_STATUSES getScmStatus();

ScmConnector::SCM_STATUSES status = scmConnector->getScmStatus();

Build

• All classes are defined within the namespace SrvStart . If you don't want to refer to this namespace directly, then include the following:

  using namespace SrvStart;

• You will need to #include the appropriate header file (CmdRunner.h or ScmConnector.h) for compilation.
• To be compatible with the DLL, you must set the /MD option for the compiler (Runtime Multithread DLL). From the GUI, select Build|Settings|C++|Code Generation, Use run-time library "Multithread DLL."
• For the linker, you will need to add srvstart.lib to the list of library modules.

Bugs

Source

SVC and SRVSTART are built using Microsoft Visual C++. I have not used any non-standard features (as far as I am aware) so the source should compile under any C++ compiler for Windows NT. (I haven't tried this.)

Full source code for the executables and DLL is included.

Support

You can email me (mailto:Nick@Rozanski.com) for support, although I can't guarantee to give any.

Please note that the Sybase features in SVC and SRVSTART are only included for backwards compatibility and may not be maintained in the future. (I have now left Sybase.)