SvcBatch is a program that allows users to run script files as Windows service.
The program's main goal is to run any application as a Windows service by using a batch file wrapper as an application launcher. This is particularly useful when running Java applications or for scripts written in Perl, Python, Ruby, etc... without the need for a specialized service wrapper.
SvcBatch was designed to be simple to use and lightweight, with a small memory footprint. Its only dependency is win32 API, and only has around 8K lines of C code. There are no configuration files or installation requirements, so it can be easily distributed alongside any application that requires Windows service functionality.
Read the rest of the documentation and check Examples for some overview and ideas how to use and deploy SvcBatch with your application.
- Github: https://github.com/mturk/svcbatch
- Docs: Documentation
The minimum supported version is Windows 7 SP1 or Windows Server 2008 R2 64-bit.
To build the SvcBatch from source code follow the directions explained in Building document. SvcBatch is targeted for Windows 64-bit versions, so make sure to use 64-bit compiler.
Starting with version 3.0.0 SvcBatch has a Service management
code that contains a subset of Microsoft's sc.exe
utility to
create, configure, manage, and delete services.
Check the managing section for some basic
guidelines.
By default SvcBatch uses System's cmd.exe
as a shell to run a batch file.
Thus the batch file is an actual service application from a
conceptual point of view.
The batch file should behave like a service and must never exit. Any exit is treated as an error because from the SCM (Service Control Manager) point of view it is the same as a service failure. On Stop or Shutdown events signaled by SCM, SvcBatch will send a CTRL_C signal to cmd.exe, as if a user hit Ctrl+C keys in interactive console session.
The simplest way to create a service for your batch file
is to put svcbatch.exe
in the same directory where your
myservice.bat
file is located. Open the command prompt and
type something like this...
> svcbatch create myservice
... or using SC
utility
> sc create myservice binPath= ""%cd%\svcbatch.exe" myservice.bat"
Check Examples section for more detailed usage.
-
Modifying services
Once installed you can edit the ImagePath value from the service's registry key:
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\myservice
In case the service was installed using SvcBatch, additional Parameters sub key is created under the service's registry key that contains arguments SvcBatch will merge at runtime with the value of ImagePath.
The changes made, will be used next the service starts.
-
Starting services
To manually start the service use either
svcbatch
,sc
or Microsoft Services GUI application.SvcBatch will append any additional arguments from the service start application to the script file's existing arguments defined at install time.
Since SvcBatch version 3.0.0, you can use the SvcBatch itself to start the service.
> svcbatch create myservice myservice.bat param1 ... > svcbatch start myservice param2 param3
When started the
myservice.bat
will receiveparam1 param2 param3
as arguments. -
Notice
If the program started from a service batch file creates its own child processes, ensure you setup the following privileges to the service:
> svcbatch configure myservice --privs=SeDebugPrivilege
This will allow SvcBatch to terminate the entire descendant process tree on shutdown in case the child process creates a process with different security credentials.
Also check the Managing Services section for further guidelines.
To get an overview on how to create and manage SvcBatch services, check the managing section for some basic guidelines.
Debugging a service can be a complex task, because the services run without interacting with the user.
In case your service fails without apparent reason, first check the Windows Event Log.
The next option is to use debug build of the SvcBatch.
Download or build svcbatch.exe compiled with _DEBUG=1
option
and replace the svcbatch.exe with this binary.
Debug version of SvcBatch will create a svcbatch_debug.log file inside the TEMP directory of the current service user account.
The typical content of the svcbatch_debug.log file might look something like the following:
The format of this log file is:
[ProcessId:ThreadId:MonthDayYear/HourMinuteSecond.Millisecond:Mode:FunctionName(line)] message
If the svcbatch_debug.log file already exists, debug messages will be appended to the end of the file.
You can rename svcbatch.exe executable to myservice.exe and modify service ImagePath registry value. When the service start, SvcBatch will use myservice_debug.log as log file. This can be useful when multiple service share the same SvcBatch executable.
To get an overview on how the SvcBatch is used with the real application, check the documentation section for some basic deployment guideline.
Here are listed some of the main features provided by SvcBatch.
By default SvcBatch, on startup, creates a Logs
directory inside its
working directory and creates an SvcBatch.log file that is used both
for internal logging and capturing output from cmd.exe
It also renames previous log files if the files are
present inside Logs
directory using the following procedure:
* If exists move SvcBatch.log to SvcBatch.log.0
* If exists move SvcBatch.log.8 to SvcBatch.log.9
This means that SvcBatch.log.9 will be overwritten, so make sure
to backup SvcBatch.log.9 before log rotation occurs if needed
* If exists move SvcBatch.log.7 to SvcBatch.log.8
* ...
* ...
* If exists move SvcBatch.log.1 to SvcBatch.log.2
* If exists move SvcBatch.log.0 to SvcBatch.log.1
* Create new SvcBatch.log and use it as current log file.
SvcBatch command line options allow users to customize
service deployments. Options are case insensitive and
defined with / or - as command switch when running in
service mode, or with -- for SvcBatch service management.
This means that -h or /H
and --Wait or --wait
can be used interchangeably.
Check the managing for more info about command line options when SvcBatch is used for managing services.
Command line option value can be either the rest of the command option or the entire next argument.
In case the value is the rest of the command option, the command switch must be / and the character after the option must be : character, followed by the actual option value.
For example:
> svcbatch create myService ... /L:log\directory ...
Is the same as
> svcbatch create myService ... -l log\directory ...
After handling switches SvcBatch will pass remaining arguments to the script interpreter.
The first argument is treated as script file. If the first argument is not the absolute path, it will be resolved relative to the service home directory.
If there are no additional arguments, SvcBatch will
append .bat
to the running Service Name.
In that case, if ServiceName
contain any of the
invalid file name characters /\:;<>?*|"
,
the service will fail and error message will be
reported to Windows Event log.
Although command options are case insensitive, use capital letters with / command switch, and lowercase letters with - command switch.
-
F [features]
Set runtime features
This option sets various runtime features. The features parameter is a combination of one or more characters, where each character sets the particular feature option.
Feature options are case sensitive, and can be listed in any order.
<B><L><N><P><Q><R><T><W><Y><0|1|2>
-
B
Generate CTRL_BREAK on service stop
This option can be used to send
ctrl+break
insteadctrl+c
signal when the service is stopping.This is useful when the service batch file uses
start /B ...
to launch multiple applications.... start /B some.exe instance1 start /B some.exe instance2 start /B some.exe instance3 ...
When using
start /B application
, the application does not receivectrl+c
signal. Thectrl+break
is the only way to interrupt the application. -
L
Use local time
This option causes all logging and rotation to use local instead system time.
-
P
Enable preshutdown service notification
When defined, SvcBatch will accept
SERVICE_CONTROL_PRESHUTDOWN
control code. The service control manager waits until the service stops or the specified preshutdown time-out value expires -
Q
Disable logging
This option disables both logging and log rotation.
Use this option when output from script file is not needed or service batch file manages logging on its own.
Notice
Any eventual log rotation option will not be processed.
-
R
Enable log rotation by control code
When defined, SvcBatch will accept custom 234 control code and initiate log rotation when this control is signaled.
Note that 234 is our custom service control code. Number 234 has been randomly chosen, since win32 API requires that this number must be larger then
127
and lower then255
.To initiate log rotation manually use the following:
> svcbatch control myService 234
In case the last log rotation was less then
2
minutes ago, or if there was no data written to the log file from the last rotation, SvcBatch will not rotate the logs. -
T
Truncate log on rotation
If set this option will truncate existing log file on log rotation instead creating a new log file.
-
Y
Write Y to child console
If set this option will write
Y\r\n
characters to script interpreter's console standard input.This option is enabled by default when cmd.exe is used, and handles
Terminate batch job (Y/N)?
prompt. -
0
Flags [0|1|2] determine how the SvcBatch will handle service failure in case it enters a
STOP
state without explicit Stop command from the SCM.This mode will set the error code when the service fails. The error message will be written to the Windows Event log and service will enter a stop state.
If the service was in
RUNNING
state the error code will be set toERROR_PROCESS_ABORTED
, otherwise the error code will be set toERROR_SERVICE_START_HANG
.You can use this mode to initialize service recovery if defined.
> sc failure myService reset= INFINITE actions= restart/10000 > sc failureflag myService 1
The upper example will restart
myService
service after10
seconds if it enters a stop state without Stop command.This is the default mode.
-
1
This mode will not set the error code when the service fails. The information message will be written to the Windows Event log and service will enter a stop state.
The typical usage of this feature is for the services that run for some time and then stop.
-
2
This mode will not report error code to the SCM when the service fails. The error message will be written to the Windows Event log. SvcBatch will call
exit(ERROR_INVALID_LEVEL)
and terminate the current service.
-
-
C [program][<[> parameters <]>]
Use alternative program for running scripts
This option allows to use alternative program program instead default cmd.exe to run the scripts.
For example:
> svcbatch create ... /C:[ powershell -NoProfile -ExecutionPolicy Bypass -File ] myservice.ps1 ...
SvcBatch will execute powershell.exe instead cmd.exe and pass [ parameters ] as arguments to the powershell.
Additional parameters for alternative shell must be enclosed inside square brackets before script file and its arguments.
Parameters for default cmd.exe interpreter are /D /E:ON /V:OFF /C.
> svcbatch create ... /C:cmd.exe [ /D /E:ON /V:OFF /C ] myservice.bat ...
If the program parameter contains any @ or % characters, SvcBatch will evaluate all environment strings in the program parameter and use it as application name.
In case the program parameter is not an absolute path, SvcBatch will search the current environment for the program[.exe] application.
-
K [depth]
Set the nested process kill depth
This option sets the depth of the process tree that SvcBatch will kill on service stop.
The valid depth range is between 0 and 4. By default this value is set to zero.
This option is used only when manually stopping the service. In case the service STOP is initiated by system shutdown, SvcBatch will not traverse its process tree, but rather let the operating system to kill all child processes.
Use this option if the service script file creates a process that do not respond to STOP command, but keeps running in the background.
-
E [name=value]
Sets environment variable
This option allows to set the contents of the specified environment variable. The content of the name environment variable is to the value.
For example:
> svcbatch create ... /E:NOPAUSE=Y /E:CATALINA_BASE=$WORK ...
This will set the
NOPAUSE
environment variable toY
, andCATALINA_BASE
to the value of the current working directory.SvcBatch will evaluate value parameter and replace each $variable string with corresponding runtime value.
If the $variable does not exits, it will be replaced by empty string.
The $WORK will be evaluated to the current working directory, $NAME will set the value to the current Service name, etc.
The runtime variable values are:
APPLICATION Program application path BASENAME Program application name DISPLAYNAME Service display name HOME Home directory LOGS Logs directory NAME Service Name RELEASE SvcBatch release version UUUID Service UUID VERSION SvcBatch version number WORK Work directory
The following example will modify
PATH
environment variable for the current process:> svcbatch create ... -e "PATH=$ProgramFiles\SomeApplication;$PATH" ...
In the upper example, each $variable will be evaluated to the current runtime value.
Each $$ character pair will be replaced by the single $ character. This allows to use $ characters as part of value without evaluating them.
> svcbatch create ... /E "SOME_VARIABLE=RUN$$1" ...
In the upper example, SvcBatch will set
SOME_VARIABLE
environment variable to the valueRUN$1
.SvcBatch will evaluate E command options in order they are defined in service configuration.
SvcBatch will first set all Private Environment Variables
After that it will evaluate and set all /E:name=value variables.
-
EE [variables]
Export private environment variables
This option exports various runtime environment variables. The variables parameter is a combination of one or more characters, where each character sets the particular environment variable.
Variables are case sensitive, and can be listed in any order.
A Program application B Program application name D Service display name H Home directory L Logs directory N Service Name R SvcBatch release version U Service UUID V SvcBatch version number W Work directory
Each variable name will be evaluated at runtime using either default or prefix or the one defined by the /EP:PREFIX command option.
A ... [PREFIX]_APPLICATION B ... [PREFIX]_BASENAME D ... [PREFIX]_DISPLAYNAME H ... [PREFIX]_HOME L ... [PREFIX]_LOGS N ... [PREFIX]_NAME R ... [PREFIX]_RELEASE U ... [PREFIX]_UUID V ... [PREFIX]_VERSION W ... [PREFIX]_WORK
The following example will export
SVCBATCH_PROCESSID
andSVCBATCH_VERSION
environment variables with the values set to their corresponding runtime values.> svcbatch create ... /EE:PV ...
This feature is usually used to export specific runtime variable(s).
The following example will only export service's home and work directories as
MYSERVICE_HOME
andMYSERVICE_WORK
environment variables:> svcbatch create myService ... /EP:@ /EE:HW ...
-
EP [prefix]
Sets private environment variables prefix
By default SvcBatch uses uppercase program name as prefix for private environment variables names.
Check Private Environment Variables section, for the list of exported variables.
To change default SVCBATCH prefix, add /EP:prefix to your service configuration.
The following example will cause SvcBatch to export ASERVICE_NAME instead default SVCBATCH_NAME, etc.
> svcbatch create ... /EP:ASERVICE ...
In case the prefix is a single @ character, SvcBatch will use service name as private environment prefix.
The following example will cause SvcBatch to export MYSERVICE_NAME instead default SVCBATCH_NAME, etc.
> svcbatch create myService ... /EP:@ ...
-
H [path]
Set service home directory
This option enables users to explicitly set the home directory.
The home directory is the location from where all relative path parameters will be resolved.
If not specified, the home directory will set to the path of the batch file if it was defined as an absolute path. Otherwise the directory of the svcbatch.exe will be used as home directory.
In case the path is relative, it will be resolved either to the directory of the batch file, if it was defined as an absolute path, or to the directory of the svcbatch executable.
The resulting path value must exist on the system or the service will fail to start, and write an error message to the Windows Event log.
-
L [path]
Set service log directory
This option allows a user to set the log directory, which is where SvcBatch will create any runtime log files.
If set, the path parameter will be used as the location where SvcBatch.log files will be created. SvcBatch will create a path directory if it doesn't exist.
If not set, SvcBatch will create and use the SVCBATCH_WORK\Logs directory as a location for log files that has to be created.
If the path is not the absolute path, it will be resolved relative to the W directory.
Notice
This directory has to be unique for each service instance. Otherwise the service will fail if another service already opened SvacBatch.log in that location.
-
LN [name]
Set log file name
This option allows a user to set the alternate log file names.
By default SvcBatch will use
SvcBatch.log
as name. To redefine default log name use the LN command option at service install:> svcbatch create ... /LN:myService.log ...
If the name parameter contains
@
characters, it will be treated as a format string to our customstrftime
function.When using
strftime
filename formatting, be sure the log file name format has enough granularity to produce a different file name each time the logs are rotated. Otherwise rotation will overwrite the same file instead of starting a new one. For example, if logfile wasservice.@Y-@m-@d.log
with log rotation at5
megabytes, but5
megabytes was reached twice in the same day, the same log file name would be produced and log rotation would overwrite the same file.Supported formatting codes
Here are listed the supported formatting codes:
@d Day of month as a decimal number (01 - 31) @F Equivalent to @Y-@m-@d @H Hour in 24-hour format (00 - 23) @j Day of the year as a decimal number (001 - 366) @m Month as a decimal number (01 - 12) @M Minute as a decimal number (00 - 59) @S Second as a decimal number (00 - 59) @s Millisecond as a decimal number (000 - 999) @w Weekday as a decimal number (0 - 6; Sunday is 0) @y Year without century, as decimal number (00 - 99) @Y Year with century, as decimal number @0 Current counter as a decimal number (0 - 9) @2 Current counter as a decimal number (00 - 99) @4 Current counter as a decimal number (0000 - 9999)
Make sure that log names contain only valid file name characters. The following are reserved characters:
< (less than) > (greater than) : (colon) ; (semicolon) " (double quote) / (forward slash) \ (backslash) | (vertical bar or pipe) ? (question mark) * (asterisk)
In case the result from
strftime
contains any of the reserved characters the function will fail. -
LM [number]
Set maximum number of log files
In case the number contains a single decimal number between
1 and 9
it will be used instead default1 .. 2
.> svcbatch create ... /LM:4
Instead rotating Svcbatch.log from
1 .. 2
it will rotate exiting log files from1 .. 4.
. -
LR [rule]
Rotate logs by size or time interval
Depending on the rule parameter service can rotate log files at desired interval, once a day at specific time or when log file gets larger then defined size.
Time and size values can be combined, which allows to rotate logs at specific time or size which ever first. For example one can define rule so that rotate logs is run each day at
17:00:00
hours or if log files gets larger then100K
bytes.To combine multiple values use the + character as value separator. The order is important.
<@Time><+><Size>
> svcbatch create ... /LR:@17:00:00+100K
If time is given without a colons, SvcBatch will use it as minutes between log rotation.
>svcbatch create ... /LR:@90+200K
The upper example will rotate logs each
90
minutes. In case log file gets larger the 200Kbytes within that interval, it will be rotated as well. In that case internal timer will be reset and next rotation will occur after90
minutes.In case rule parameter is
@0
SvcBatch will rotate log files each day at midnight. This is the same as defining/LR:@00:00:00
.In case rule parameter is
@60
SvcBatch will rotate log files every full hour.In case rule parameter for rotation based on log file size is less then
1K
(1024 bytes), SvcBatch will not rotate logs by size.The rule parameter uses the following format:
<[@hh:mm:ss|@minutes]><+><size[B|K|M|G]>
-
S [script][<[> arguments <]>]
Execute script file on service stop or shutdown
If defined, on shutdown or stop event the service will create separate
svcbatch.exe
process and call script. The purpose of that file is to use some sort ofIPC
mechanism and signal the service to exit.This is particularly useful for services that do not handle
CTRL_C_EVENT
or have specific shutdown requirements.In case the script equals to NUL, SvcBatch will only pass additional arguments to the script interpreter. Service will fail to start if the additional argument(s) were not defined.
In case the script starts with ./ or .\, SvcBatch will use the string following the ./ or .\ as script file without checking for its existence.
In case the script equals to @, SvcBatch will use the main service script file for shutdown, add pass stop string as the argument to that script file, if the additional argument(s) were not defined.
To set additional arguments for stop script enclose them inside square brackets
[ ... ]
.> svcbatch create ... /S:stop.bat /S:[ --connect --command=:shutdown ] ... ... > svcbatch create ... /S:@ ... ... > svcbatch create ... /S:@ [ used instead default stop ] ...
-
SM [number]
Set maximum number of stop log files
Default maximum number of stop log files is
0
(zero), which means that no log rotation will be performed for stop script logging. To enable log rotation for stop logging, set the number parameter value between1 and 9
.> svcbatch create ... /SM:2 /SN:myService.stop.log
This will rotate stop log files from
1 .. 2
.Notice
If this option is defined, and SN option was not defined, SvcBatch will use default
SvcBatch.stop.log
as stop log name. -
SN [name]
Set stop log file name
This option allows a user to enable stop logging for scripts defined by S option.
> svcbatch create ... /SN:myService.stop.log ...
The name parameter is handled the same as described with LN command option.
-
ST [timeout]
Set stop timeout in seconds
This option sets the timeout when service receives stop or shutdown signal. The valid timeout range is between
2
and120
seconds (two minutes).By default this value is set to
10
seconds.Also make sure to check the WaitToKillServiceTimeout value specified in the following registry key:
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control
If the operating system is rebooting, this value is used as time limit.
-
T [path]
Set temp directory
This option allows a user to set different temp directory then the one defined by the service account environment.
If the path is not the absolute path, it will be resolved relative to the W directory.
SvcBatch will set TEMP and TMP environment variables to that directory.
In case the directory specified by path parameter does not exists, it will be created.
-
W [path]
Set service working directory
This option enables users to explicitly set the working directory. When batch file is executed its current directory is set to this path.
If not specified, the working directory is set to the home directory defined using H option. Check H command option for more details.
If the path is not the absolute path, it will be resolved relative to the H directory.
Notice
If defined, the working directory must exist and have read and write access rights for the current process.
SvcBatch sets a few private environment variables that provide more info about running environments to batch files. Those variable by default have SVCBATCH prefix, determined from the program executable name.
Here is the list of environment variables that SvcBatch sets for each instance:
-
SVCBATCH_HOME
This variable is set to the service home directory.
-
SVCBATCH_LOGS
This variable is set to the service's output directory.
In case the logging is disabled, by using /F:Q command option, this variable is set to the SVCBATCH_WORK directory.
-
SVCBATCH_NAME
This variable is set to the actual service name defined with
svcbatch create [service name] ...
@echo off rem rem Simple example rem echo Running service %SVCBATCH_NAME%
-
SVCBATCH_UUID
This is the service's unique identifier in following hexadecimal format
abcd-01234567-89ab-cdef-0123-456789abcdef
. The first four digits are current process id, and remaining digits are randomly generated at service startup.The SVCBATCH_UUID environment variable can be used inside batch file when unique identifier is needed.
rem rem Create unique temp directory rem md "%TEMP%\%SVCBATCH_UUID%" ... ... do some work using that directory ... rd /S /Q "%TEMP%\%SVCBATCH_UUID%"
-
SVCBATCH_WORK
This variable is set to the service working directory.
The working directory is set to SVCBATCH_HOME directory, unless the W command option was configured.
This variable is set as current directory for the shell process launched from SvcBatch, and as base directory for SVCBATCH_LOGS in case the L parameter was defined as relative path.
Notice
In case you rename SvcBatch executable from svcbatch.exe to for example myservice.exe, SvcBatch will use MYSERVICE as prefix for those variables. In that case it will export MYSERVICE_NAME, MYSERVICE_HOME, etc.
In case the /EP:@ or /EP:PREFIX command option is defined, it will take precedence over this feature.
Important
Make sure to use only ASCII alphanumeric and underscore (_
)
characters as executable name, or the service will fail to start.
When you type sc.exe stop myservice
or when your machine gets into the
shutdown state, SvcBatch running as a service will receive
stop or shutdown event. SvcBatch will send CTRL_C_EVENT
to its
child processes or run shutdown batch file in case
/S [batchfile] was defined at install time.
It is up to the application started from batch file to
handle this event and do any cleanup needed and then exit.
By default, on startup, SvcBatch writes 'Y' to cmd.exe
stdin,
to handle that obnoxious Terminate batch job (Y/N)?
prompt.
If batch file or any of downstream processes do not exit within stop timeout,
SvcBatch will give another 20 seconds for all processes to exit.
After that timeout it will simply kill each descendant process
that originated from svcbatch.exe.
The simplest way to obtain the version information
is to right click on the svcbatch.exe
from Windows File
Explorer, click on Properties, and then on the Details tab.
Another way to get SvcBatch version and build information is to open command prompt and type
> svcbatch.exe version
SvcBatch 1.2.3.4 ...
>
Make sure to use the correct information when filing bug reports.
SvcBatch logs any runtime error to Windows Event Log.
Use Windows Event Viewer and check Windows Logs/Application/YourServiceName
events.
SvcBatch have limits for the following features:
-
Service Name
The Service Name must consists of only ASCII characters except the following set:
< (less than) > (greater than) : (colon) ; (semicolon) " (double quote) / (forward slash) \ (backslash) | (vertical bar or pipe) ? (question mark) * (asterisk)
Service Name must start with alphanumeric character, and its length is limited to 255 characters.
Service will fail to start if the upper criteria is not met.
-
Program File Name
Default Program File Name is svcbatch.exe.
Program File Name can contain only alphanumeric ASCII characters including underscore (
_
) character, and must end with .exe file extension. -
File name length
The maximum file name length must be less then 2040 characters, and is defined by the
#define SVCBATCH_PATH_SIZ 2040
macro inside svcbatch header file -
Maximum number of arguments
The maximum number of arguments that can be passed to the command processor is limited to 32, and is defined by the
#define SVCBATCH_MAX_ARGS 32
macro inside svcbatch header fileThis option also defines the maximum number of parameters passed to the command interpreter when C command option is used.
The code in this repository is licensed under the Apache-2.0 License.