Windows Service Manager Module that wraps for the win32service api
Project description
Python Windows Service Manager is a python package that helps to easily manage windows services, mirroring the functionality of the Windows Service Controller Utility (sc.exe). It allows to easily manage both Driver and Win32 services. The following can be achieved using this package:
Create, Remove, or Update a service configuration
Query a specific or all Service Statuses
Get a service configuration
Verify a service exists
Start, Stop, Pause, Continue, Interrogate a service
Pre-requisites
- pywin32>=219
This cannot be installed via pypi. This has to be the precompiled version.
Installation
Clone this repository
Put the repo dir in your PYTHONPATH
Run:
python setup.py install
How to Run Unit Tests
pip install nose, mock
From the module’s root directory, run ‘nosetests .’
How to Run the Example
Download the package
From the module’s root directory, run ‘python example.py’
Note: Due to the way Windows Services work, you need to have the powershell scipt, testService.ps1, in the same directory as the example.py
Usage
This module attempts to follow the ORM design Pattern, where the Class WindowsServiceConfigurationManager would be your context, and object that represents the data store is a ServiceEntity.
WindowsServiceConfigurationManager
This is the entry point for all operations. This module has static methods that: - Creates or Gets a Service, and returns a Entity object that represents that service - Query All Service Statuses - Verify a service exists - Gets a specific service’s status
The following Describes these operations in detail:
Create a New Service:
The CreateService() function takes a parameter of Type NewServiceDefinition. The following describes the NewServiceDefinition constructor and its arguments:
NewServiceDefinition:
- serviceName *(Required)*: The name of the service.
Valid Values: Any non empty string
- displayName *(Required)*: Indicates the friendly name that identifies the service to the user
Valid Values: Any non empty string
- binaryPathName *(Required)*: Specifies the path to the executable file for the service.
Validate Values: Any non empty string that points to an executable
- startType: Indicates how and when the service is started
Valid String Values: AUTO_START, DEMAND_START, BOOT_START, DISABLED, SYSTEM_START, INTERACTIVE_SHARE_PROCESS, INTERACTIVE_OWN_PROCESS Default Value: DEMAND_START
- serviceType: Represents the type of the service
Valid String Values: WIN32_SHARE_PROCESS, WIN32_OWN_PROCESS, KERNEL_DRIVER, FILE_SYSTEM_DRIVER Default Value: WIN32_OWN_PROCESS
- errorControl: Specifies how to proceed if the driver for the service or device fails to load or initialize properly
Valid String Values: ERROR_CRITICAL, ERROR_IGNORE, ERROR_NORMAL, ERROR_SEVERE Default Value: ERROR_NORMAL
- loadOrderGroup: The name of the load ordering group of which this service is a member
Valid Value: String of Group Name Default Value: None
- dependencies:
Valid Value: Array of Existing Service Names Default Value: None
- serviceStartName: Name of the account in which the service runs
Valid Value: A valid user account as a string Default Value: The System Account
- description: The description of the service
Valid Value: Any string Default Value: An empty string
- failureActions: Represents the action the service controller should take on each failure of a service
Valid Value: FailureActionConfigurationType Default Value: None
*See ‘Complex Example for Creating Service’ for an example, or the Section that describes the ‘FailureActionConfigurationType’
- failureFlag: Specifies whether recovery actions will be triggered when a service stops as the result of an error
Valid Value: Boolean Default Value: False
- preShutdownInfo: The time-out value, in milliseconds.
Valid Value: long or int Default Value: 180,000 milliseconds
- serviceSIDInfo: Represents a service security identifier
Valid String Value: SID_TYPE_NONE, SID_TYPE_RESTRICTED, SID_TYPE_UNRESTRICTED Default Value: SID_TYPE_UNRESTRICTED
- delayedAutoStartInfo: The value that indicates whether the service should be delayed from starting until other automatically started services are running.
Valid Value: Boolean Default Value: False
#Most simplistic example of creating a service
from pywinservicemanager.WindowsServiceConfigurationManager import CreateService
from pywinservicemanager.NewServiceDefinition import NewServiceDefinition
serviceName = 'TestService'
displayName = 'MyTestService'
binaryPathName = 'c:\\myBinary.exe'
newServiceDefinition = NewServiceDefinition(serviceName=serviceName,
displayName=displayName,
binaryPathName=binaryPathName)
myService = CreateService(newServiceDefinition)
# Note that the Create Service Method just creates the entity in memeory.
# To save it to the 'DataStore', you must call Save()
myService.Save()
#Most complex example of creating a service
from pywinservicemanager.WindowsServiceConfigurationManager import CreateService
from pywinservicemanager.NewServiceDefinition import NewServiceDefinition
import pywinservicemanager.ConfigurationTypes as ConfigurationTypes
serviceName = 'TestService'
displayName = 'MyTestService'
binaryPathName = 'c:\\myBinary.exe'
startType = 'DEMAND_START'
serviceType= 'WIN32_OWN_PROCESS'
errorControl= 'ERROR_IGNORE'
loadOrderGroup = None
dependencies= ['nsi']
description= 'This is a test Service'
failureFlag = False
preShutdownInfo= 18000
serviceSIDInfo = 'SID_TYPE_UNRESTRICTED'
userName = None
password = None
delayedAutoStartInfo = False
failureActionList = []
delay = 1000
failureActionList.append(ConfigurationTypes.FailureActionTypeFactory.CreateRestartAction(delay))
failureActionList.append(ConfigurationTypes.FailureActionTypeFactory.CreateRunCommandAction(delay))
resetPeriod = 1
rebootMsg = 'MyRebootMessage'
commandLine = 'MyCommandLine'
failureActions = FailureActionConfigurationType(failureActionList, resetPeriod, rebootMsg, commandLine)
newServiceDefinition = NewServiceDefinition(serviceName=serviceName,
displayName=displayName,
binaryPathName=binaryPathName,
startType=startType,
serviceType=serviceType,
errorControl=errorControl,
loadOrderGroup=loadOrderGroup,
dependencies=dependencies,
serviceStartName=userName,
description=description,
failureActions=failureActions,
failureFlag=failureFlag,
preShutdownInfo=preShutdownInfo,
serviceSIDInfo=serviceSIDInfo,
delayedAutoStartInfo=delayedAutoStartInfo)
myService = CreateService(newServiceDefinition)
# Note that the Create Service Method just creates the entity in memeory.
# To save it to the 'DataStore', you must call Save()
myService.Save(password)
Delete a Service:
from pywinservicemanager.WindowsServiceConfigurationManager import GetService
serviceName = "TestService"
myService = GetService(serviceName)
# Note that the GetService Method reads for the data store and creates the entity in memeory.
# To delete it from the 'DataStore', you must call Delete()
myService.Delete()
Query All Services Statuses: Returns a list of each installed service’s status. (Please see status definition below for more details)
from pywinservicemanager.WindowsServiceConfigurationManager import QueryAllServicesStatus
statuses = QueryAllServicesStatus()
print statuses
Service Exists:
from pywinservicemanager.WindowsServiceConfigurationManager import ServiceExists
serviceName = 'TestService'
serviceExists = ServiceExists(serviceName)
print serviceExists
Get Service Status: Returns a single service’s status (Please see status definition below for more details)
from pywinservicemanager.WindowsServiceConfigurationManager import GetServiceStatus
serviceName = 'TestService'
serviceStatus = GetServiceStatus(serviceName)
print serviceStatus
ServiceEntity
This is the object that maps to the service.
- The object contains the following commands for each service:
Save
Delete
Start
Stop
Pause
Continue
Interrogate
GetServiceStatus
UpdateConfiguration
Exists
You need to make sure that the commands Pause, Continue, and Interrogate are able to be excepted by the service. The accepted commands are dependent on 2 things. First, if the service is configurated to accept such commands, and second, if the current state of the service allows that command to be called on the service. The code examples below shows how to deal with this. Furthermore, if a service is not in a “Running” state, than Stop cannot be called. Vis-a-versa, if a service is not in a “Stopped” state, then Start cannot be called.
UpdateConfiguration: Used to update a service’s configuration in memeory. You must call the save method to persist the service.
from pywinservicemanager.WindowsServiceConfigurationManager import GetService
serviceName = 'TestService'
myService = GetService(serviceName)
myService.UpdateConfiguration('StartType', 'DEMAND_START')
myService.Save()
Save: Saves the current state of the ServiceEntity as a service in the OS. You can pass a password as an argument to this function if one is needed, the default value is ‘None’
from pywinservicemanager.WindowsServiceConfigurationManager import GetService
serviceName = 'TestService'
myService = GetService(serviceName)
myService.UpdateConfiguration('ServiceStartName', 'MyDomain\\MyNewUser')
myService.Save('MyNewPassword')
Delete: Deletes the Service Deletes a service. Please note that you if your service is running, you will need to stop the service for it to be deleted. Also, if anything has a handle open to the service, those need to be closed as well. If Delete() is called on service in which a handle is open, then it will be ‘Marked for Deletion’ and will not be deleted until all handles are closed.
from pywinservicemanager.WindowsServiceConfigurationManager import GetService
serviceName = 'TestService'
myService = GetService(serviceName)
myService.Delete()
Start: Deletes the Service Starts a given service that has is stopped. If the service is not stopped, an exception will be thrown. Also, if the service does not return from the Start command within 30 seconds, a TimeoutException is thrown
from pywinservicemanager.WindowsServiceConfigurationManager import GetService
serviceName = 'TestService'
myService = WindowsServiceConfigurationManager.GetService(serviceName)
myService.Start()
Stop: Stops the Service Stops a given service that is started. If the service is not started, an exception will be thrown. Also, if the service does not return from the Stop command within 30 seconds, a TimeoutException is thrown
from pywinservicemanager.WindowsServiceConfigurationManager import GetService
serviceName = 'TestService'
myService = WindowsServiceConfigurationManager.GetService(serviceName)
myService.Stop()
Continue: Continues the Service after it was paused Stops a given service that is Paused and/or has the value ACCEPT_PAUSE_CONTINUE in ControlsAccepted. If not, an exception will be thrown. Also, if the service does not return from the Continue command within 30 seconds, a TimeoutException is thrown
from pywinservicemanager.WindowsServiceConfigurationManager import GetService
serviceName = 'TestService'
myService = GetService(serviceName)
status = myService.GetServiceStatus()
if 'ACCEPT_PAUSE_CONTINUE' in status['ControlsAccepted']:
myService.Continue()
Pause: Pauses the Service Pauses a given service that is Paused and/or has the value ACCEPT_PAUSE_CONTINUE in ControlsAccepted. If not, an exception will be thrown. Also, if the service does not return from the Pause command within 30 seconds, a TimeoutException is thrown
from pywinservicemanager.WindowsServiceConfigurationManager import GetService
serviceName = 'TestService'
myService = GetService(serviceName)
myServiceStatus = myService.GetServiceStatus().Status
if 'ACCEPT_PAUSE_CONTINUE' in status['ControlsAccepted']:
myService.Pause()
Interrogate: Interrogates the Service
from pywinservicemanager.WindowsServiceConfigurationManager import GetService
serviceName = 'TestService'
myService = GetService(serviceName)
myService.Interrogate()
GetServiceStatus: Deletes the Service Returns a the service’s status (Please see status definition below for more details)
from pywinservicemanager.WindowsServiceConfigurationManager import GetService
serviceName = 'TestService'
myService = WindowsServiceConfigurationManager.GetService(serviceName)
status = myService.GetServiceStatus()
print status
Exists: Deletes the Service Returns if the service exists
from pywinservicemanager.WindowsServiceConfigurationManager import Exists
serviceName = 'TestService'
myService = WindowsServiceConfigurationManager.GetService(serviceName)
print myService.Exists()
FailureActionConfigurationType
Represents the action the service controller should take on each failure of a service. A service is considered failed when it terminates without reporting a status of SERVICE_STOPPED to the service controller
- The constructor of this object takes the following parameters:
- failureActionsTypeList: List of FailureActionType Objects
Valid Value: List of FailureActionType Objects (see below)
Default:Value None
- resetPeriodType: The time after which to reset the failure count to zero if there are no failures, in seconds
Valid Value: int or ResetPeriodType(see below)
Default:Value None
- rebootMessageType: The message to be broadcast to server users before rebooting in response to the SC_ACTION_REBOOT service controller action
Valid Value: string or RebootMessageType (see below)
Default:Value None
- commandLineType: The command line of the process for the CreateProcess function to execute in response to the SC_ACTION_RUN_COMMAND service controller action. This process runs under the same account as the service.
Valid Value: string or CommandLineType (see below)
Default:Value None
Example:
import pywinservicemanager.ConfigurationTypes as ConfigurationTypes
failureActionList = []
delay = 1000
failureActionList.append(ConfigurationTypes.FailureActionTypeFactory.CreateRestartAction(delay))
failureActionList.append(ConfigurationTypes.FailureActionTypeFactory.CreateRunCommandAction(delay))
resetPeriod = ConfigurationTypes.FailureActionConfigurationResetPeriodType(1)
rebootMsg = ConfigurationTypes.FailureActionConfigurationRebootMessageType('MyRebootMessage')
commandLine = ConfigurationTypes.FailureActionConfigurationCommandLineType('MyCommandLineCommand')
failureActions = ConfigurationTypes.FailureActionConfigurationType(failureActionList, resetPeriod, rebootMsg, commandLine)
#or
failureActionList = []
delay = 1000
failureActionList.append(ConfigurationTypes.FailureActionTypeFactory.CreateRestartAction(delay))
failureActionList.append(ConfigurationTypes.FailureActionTypeFactory.CreateRunCommandAction(delay))
resetPeriod = 1
rebootMsg = 'MyRebootMessage'
commandLine = 'MyCommandLine'
failureActions = ConfigurationTypes.FailureActionConfigurationType(failureActionList, resetPeriod, rebootMsg, commandLine)
FailureActionType
Represents an action that the service control manager can perform.
- A FailureAction type can be reurned by the factory object FailureActionTypeFactory, where there are 4 methods defined and an int which represents the delaly as the input parameter:
- Factory Methods:
FailureActionTypeFactory.CreateNoAction(delay): No action.
FailureActionTypeFactory.CreateRestartAction(delay): Restart the service.
FailureActionTypeFactory.CreateRebootAction(delay): Reboot the computer. If the service uses the reboot action, the caller must have the SE_SHUTDOWN_NAME privilege. For more information, see Running with Special Privileges.
FailureActionTypeFactory.CreateRunCommandAction(delay): Run a command.
delay: The time to wait before performing the specified action, in milliseconds.
Example:
import pywinservicemanager.ConfigurationTypes as ConfigurationTypes
myAction = ConfigurationTypes.FailureActionTypeFactory.CreateRestartAction(300)
ResetPeriodType
The time after which to reset the failure count to zero if there are no failures, in seconds. The input is of time int
Example:
import pywinservicemanager.ConfigurationTypes as ConfigurationTypes
resetPeriod = ConfigurationTypes.FailureActionConfigurationResetPeriodType(1)
FailureActionConfigurationRebootMessageType
The message to be broadcast to server users before rebooting in response to the SC_ACTION_REBOOT service controller action. If this value is None, the reboot message is unchanged. If the value is an empty string (“”), the reboot message is deleted and no message is broadcast.
Example:
import pywinservicemanager.ConfigurationTypes as ConfigurationTypes
rebootMessage = ConfigurationTypes.FailureActionConfigurationRebootMessageType("My Reboot Message")
FailureActionConfigurationRebootMessageType
The message to be broadcast to server users before rebooting in response to the SC_ACTION_REBOOT service controller action. If this value is None, the reboot message is unchanged. If the value is an empty string (“”), the reboot message is deleted and no message is broadcast.
Example:
import pywinservicemanager.ConfigurationTypes as ConfigurationTypes
rebootMessage = ConfigurationTypes.FailureActionConfigurationRebootMessageType("My Reboot Message")
FailureActionConfigurationRebootMessageType
The command line of the process for the CreateProcess function to execute in response to the SC_ACTION_RUN_COMMAND service controller action. This process runs under the same account as the service. If this value is None, the command is unchanged. If the value is an empty string (“”), the command is deleted and no program is run when the service fails.
Example:
import pywinservicemanager.ConfigurationTypes as ConfigurationTypes
commandLine = ConfigurationTypes.FailureActionConfigurationCommandLineType("myCmd.exe")
Further Information
For more information the windows API implemented in the package and/or how the service controller utility works, please consult the win32service documentation.
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Hashes for pywinservicemanager-1.0.0.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | f0d1c18295eb8c6982635b84999631e81aec6de0fe293747725701397103b676 |
|
MD5 | f9c76e4d0476e23628e3dc485fa6b185 |
|
BLAKE2b-256 | 1ffd3ac3390cf0025ffaf96c87dbe91e52ce03a11d6c837defe954c362df94cd |