Services Quick Start
This Quick Start Guide supplements the information on Windows NT Services, and my programmatic support for it, that you can find on the Web here.
I really recommend that you read that page first! But if you are too busy, this page will quickly set you up with SRVSTART. It also includes some Frequently-Asked Questionsand a short Troubleshooting Guide.
This page changes regularly.
The date of last update is at the bottom of the page.
1 Copyright and Distribution
This article is Copyright (C) 2000 Nick Rozanski.
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.
Modify Windows NT service settings at your own peril.
Making incorrect changes can render Windows NT unuseable.
If you don't know what you are doing, don't mess about with services!
2 Getting Started with SRVSTART
Let's assume that you want to run the following command:
C:\MYPROG\MYPROG.EXE -a -b -c xxxx yyyy zzz
as a Windows NT service called MY_SERVICE.
Make sure before you start that you have the most recent version of SRVSTART. (In particular, the install step is not supported under version 1.0.)
Unpack the SRVSTART executables to a directory in your $PATH:
- srvstart.exe - SRVSTART executable
- srvstart.dll - SRVSTART library
- logger.dll - LOGGER library
(If you're not sure where to put these files, just unpack them to C:\WINNT\SYSTEM32).
- If you don't already have it, copy the Microsoft run-time library to a directory in your system $PATH.
Create a text file called, say, C:\SRVSTART\SRVSTART.INI.
This is your configuration file, which will tell SRVSTART about your service.
Using a text editor such as Notepad place the following directives in this configuration file.
[MY_SERVICE] startup=C:\MYPROG\MYPROG.EXE -a -b -c xxxx yyyy zzz
Always use full pathnames in the configuration file. Relying on $PATH is insecure and may not work.
(Substitute the name of your service for MY_SERVICE, and the actual command line of your service program for the c:\myprog\myprog.exe ... bit. Blank lines and lines starting with the hash character # are ignored.)
Open a Command Prompt in Windows NT.
Install your service by typing the following command:
srvstart.exe install MY_SERVICE -c C:\SRVSTART\SRVSTART.INI
(Again, substitute the name of your service for MY_SERVICE, and the path name of your configuration file for C:\SRVSTART\SRVSTART.INI).
From the Command Prompt, type the command
net start MY_SERVICE
(Substitute the name of your service for MY_SERVICE).
The service should start without errors.
If necessary, use Control Panel | Services to set the appropriate start-up mode for you service.
Use 'automatic' if you want the service to start automatically when Windows NT starts up.
3 =SRVSTART;?> Frequently-Asked Questions
Q: What's the latest version of SRVSTART?
A: You can always pick up the latest version from my software page.
Q: Does SRVSTART work on Windows 2000? Windows 2003? Windows XP?
A: Yes. I am not aware of any limitations in using SRVSTART on these platforms compared with Windows NT (for which it was originally written).
Q: Does SRVSTART work on Windows 95/98/Me?
A: These operating systems do not really have the concept of a 'service', so no.
You can still use SRVSTART in command mode on these operating systems, if you find this useful. (Note that I have not tested the software on Windows Me.)
Q: Do I need to use a configuration file?
A: Not necessarily. You can specify most options to SRVSTART on its command line.
But if you want to change an option, you have to re-install the service. With a configuration file, you only have to edit the file, and restart the service. I recommend using one.
At a minimum, the configuration file should have one line with the service name in brackets, eg [MY_SERV], and an associated startup line. startup (and all other directives) must be in lower case.
Q: Where does the service find its environment variables?
A: A service only knows about the 'system' environment variables, not those defined for a user (unless you start the service as a specific user).
You can define environment variables using the env directive.
Q: Can I use SRVSTART to run a batch file?
A: Yes, but I would not recommend it. If the batch file starts another process or program, then stopping the service using the SCM will not stop that other program (because SRVSTART does not know about it).
Q: Where are error message logged?
A: In command mode they are written to stdout (ie they are displayed). In service mode, messages are written to the Application Event Log. (Use Event Viewer to view them.)
You can change this default behaviour using the -o option of SRVSTART.
Q: How can I get rid of the messages which are logged when the service starts?
A: Add the -d 0 switch to the SRVSTART command line.
Q: What user does the service start as?
A: The service starts using a special user called Localsystem. This user has all privileges on the local machine but no network privileges. So, in particular, it cannot connect to network drives or printers.
If you want to start the service as a named Windows NT User then you can change this using my SVC program or the ServPanel utility. If you do this you will have to manually update the password (again using SVC) if the user's password changes.
Q: Does =SRVSTART;?> use or change the Windows NT Registry?
A: No. (Apart from the Registry changes due to installing services, of course.)
Q: How do I uninstall =SRVSTART;?>?
A: As follows.
- Stop and remove any services which are currently using SRVSTART.
- Delete any configuration files you may have created.
- Delete the SRVSTART executables (see above).
Q: What directory does my service start in?
A: By default, Windows NT starts every service in C:\WINNT\SYSTEM32. If you want the service to start in another directory, use the startup_dir directive in your configuration file.
Q: What is the difference between install and install_desktop?
A: If the program that you are running interacts with the user (opens a dialog box or whatever), then install the service using install_desktop. Otherwise, use install.
Q: Can I use =SRVSTART;?> to run Java applications?
A: Yes. The command line should invoke the Java Virtual Machine with the appropriate class name. You will probably have to set the startup directory using the startup_dir directive, and the class path using the env directive.
Note that there is apparently a problem with the 1.3 Java VM whereby the application stops if the user logs off. This is a Java VM 1.3 bug. Get round it by using another version of the JVM!
Q: Could you enhance =SRVSTART;?> to ...?
Q: Why do Event Log message all start with "The description for Event ID 0 ... could not be found"?
A: Like many other utilities, SRVSTART does not register its error messages with Windows NT. (It's kind of invasive and a lot of hassle to program ...)
This feature is 'by design', as they say.
Q: What does the error message "error 1067: the process terminated unexpectedly." mean?
A: This usually means that SRVSTART has encountered an error trying to start your service. Details should be logged in the Windows NT Event Log.
There are a number of things you should check:
- Check that the name of your service, the name of its section in the configuration file, and the service name parameter in the SRVSTART command line all match. (They must all be of the same case, eg MY_SERV and my_serv are different.)
- Check that the parameters to SRVSTART are correct. The case of switches is significant, eg use -c not -C.
- Check that the configuration file is correctly-structured. At a minimum, the configuration file should have one line with the service name in brackets, eg [MY_SERV], and an associated startup line. startup (and all other directives) must be in lower case.
- Check that you have provided a full path name to the startup directive in your configuration file.
- If you used srvstart install or srvstart install_desktop to install SRVSTART, make sure that you provided a full path name to the control file at install time. (Thanks to Eugen Rieck for that tip.)
Q: What does the error message "Error: 2140 An internal Windows NT error occured." mean?
A: This message is sometimes displayed if you try and start your service from Windows Control Panel.
It means that SRVSTART has encountered an error trying to start your service. Troubleshoot this as described above for error 1067.
Note: I am trying to understand why NT sometimes returns an error 1067 and sometimes an error 2140 when a service fails to start. If you have any thoughts on this please let me know.
Q: What does the error message "An invalid parameter was supplied to a function or method." mean?
A: This message appears in the NT Event Log. It means that a parameter supplied to SRVSTART is invalid. There should be a preceeding message saying what the problem is. Check your configuration file for correctness.
Q: What does the error message "Exception 6 in Class 'CmdRunner' method 'start()'." mean?
A: This means that an invalid parameter has been supplied to SRVSTART.
It also occurs if you fail to provide a startup directive in the configuration file. Check that you have spelled the service name correctly in your configuration file, and that there is a startup directive (the word startup must be in lower case).
Q: What if my service starts, but fails to run?
A: In other words, SRVSTART has tried to start your program, but it failed to start, stopped immediately or crashed. SRVSTART can't always distinguish between some of these scenarios and your program terminating normally.
Here are some suggestions:
- Check any debug or error messages generated by your program.
- Check that the command line you have given SRVSTART is correct (and includes full path names rather than just file names).
- Check that the executable exists and that all parameters are valid etc.
- If the command requires certain environment variables or startup directory, add these to your configuration file.
- You can try running SRVSTART from the command line using the cmd or any keywords.
Q: Where can I get more help?
A: If you have a problem not covered by this FAQ, you can email me. I'll help you if I can (but I do have a job, a family and an occasional social life ...).
If you do email me, please tell me a bit more than "your program doesn't work." (It does, actually :-). The contents of your configuration file, and the error messages received, are a good start.