pywinservicemanager 1.0.5

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

pypiwin32>=219

Installation

• Clone this repository
• Put the repo dir in your PYTHONPATH
• Run:

python setup.py install

How to Run Unit Tests

1. pip install nose, mock
2. From the module’s root directory, run ‘nosetests .’

How to Run the Example

1. Download the package
2. 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:

1. serviceName *(Required)*: The name of the service.

   Valid Values: Any non empty string

2. displayName *(Required)*: Indicates the friendly name that identifies the service to the user

   Valid Values: Any non empty string

3. binaryPathName *(Required)*: Specifies the path to the executable file for the service.

   Validate Values: Any non empty string that points to an executable

4. 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

5. 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

6. 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

7. loadOrderGroup: The name of the load ordering group of which this service is a member

   Valid Value: String of Group Name Default Value: None

8. dependencies:

   Valid Value: Array of Existing Service Names Default Value: None

9. serviceStartName: Name of the account in which the service runs

   Valid Value: A valid user account as a string Default Value: The System Account

10. description: The description of the service

    Valid Value: Any string Default Value: An empty string

11. 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’

12. failureFlag: Specifies whether recovery actions will be triggered when a service stops as the result of an error

    Valid Value: Boolean Default Value: False

13. preShutdownInfo: The time-out value, in milliseconds.

    Valid Value: long or int Default Value: 180,000 milliseconds

14. serviceSIDInfo: Represents a service security identifier

    Valid String Value: SID_TYPE_NONE, SID_TYPE_RESTRICTED, SID_TYPE_UNRESTRICTED Default Value: SID_TYPE_UNRESTRICTED

15. 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 running, the function will just return. 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 stopped, the function will just return. 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()

• Restart: Restart the Service Restarts a given service that is started. If the service is stopped, this is equivelent to just calling start. If the service is running, then service will be stopped and then started. Also, if the service does not return from the Stop or Start command within 30 seconds, a TimeoutException is thrown

from pywinservicemanager.WindowsServiceConfigurationManager import GetService

serviceName = 'TestService'
myService = WindowsServiceConfigurationManager.GetService(serviceName)
myService.Restart()

• 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:

1. failureActionsTypeList: List of FailureActionType Objects

   • Valid Value: List of FailureActionType Objects (see below)
   • Default:Value None

2. 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

3. 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

4. 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)

More information about FailureActionConfiguration Mapping.

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:

1. 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.

2. delay: The time to wait before performing the specified action, in milliseconds.

Example:

import pywinservicemanager.ConfigurationTypes as ConfigurationTypes
myAction = ConfigurationTypes.FailureActionTypeFactory.CreateRestartAction(300)

More information about FailureAction.

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.