Windows Service module.
New in version Carbon: Rewritten to use PyWin32
salt.modules.win_service.
available
(name)¶Check if a service is available on the system.
True
if the service is available, False
otherwiseCLI Example:
salt '*' service.available <service name>
salt.modules.win_service.
config
(name, bin_path=None, display_name=None, svc_type=None, start_type=None, error=None, group=None, tag=None, depend=None, obj=None, password=None, **kwargs)¶Deprecated since version Carbon: Use service.modify
instead
Modify the named service. Because this is deprecated it will use the passed
parameters to run service.modify
instead.
Args:
name (str): Specifies the service name. This is not the display_name
bin_path (str): Specifies the path to the service binary file. Backslashes must be escaped, eg: C:\path\to\binary.exe
display_name (str): the name to be displayed in the service manager
svc_type (str): Specifies the service type. Default is
own
. Valid options are as follows:
- kernel: Driver service
- filesystem: File system driver service
- adapter: Adapter driver service (reserved)
- recognizer: Recognizer driver service (reserved)
- own (default): Service runs in its own process
- share: Service shares a process with one or more other services
- start_type (str): Specifies the service start type. Valid options are as
- follows: - boot: Device driver that is loaded by the boot loader - system: Device driver that is started during kernel initialization - auto: Service that automatically starts - manual (default): Service must be started manually - disabled: Service cannot be started
error (str): The severity of the error, and action taken, if this service fails to start. Valid options are as follows:
- normal (normal): Error is logged and a message box is displayed
- severe: Error is logged and computer attempts a restart with the last known good configuration
- critical: Error is logged, computer attempts to restart with the last known good configuration, system halts on failure
- ignore: Error is logged and startup continues, no notification is given to the user
- group: The name of the load order group to which this service
- belongs
depend (list): A list of services or load ordering groups that must start before this service
obj (str): The name of the account under which the service should run. For
own
type services this should be in thedomain\username
format. The following are examples of valid built-in service accounts:
- NT Authority\LocalService
- NT Authority\NetworkService
- NT Authority\LocalSystem
- .\LocalSystem
password (str): The password for the account name specified in
account_name
. For the above built-in accounts, this can be None. Otherwise a password must be specified.
CLI Example:
salt '*' service.config <service name> <path to exe> display_name='<display name>'
salt.modules.win_service.
create
(name, bin_path, exe_args=None, display_name=None, description=None, service_type='own', start_type='manual', start_delayed=False, error_control='normal', load_order_group=None, dependencies=None, account_name='.\\LocalSystem', account_password=None, run_interactive=False, **kwargs)¶Create the named service.
New in version 2015.8.0.
Args:
name (str): Specifies the service name. This is not the display_name
bin_path (str): Specifies the path to the service binary file. Backslashes must be escaped, eg: C:\path\to\binary.exe
exe_args (str): Any additional arguments required by the service binary.
display_name (str): the name to be displayed in the service manager
description (str): A description of the service
service_type (str): Specifies the service type. Default is
own
. Valid options are as follows:
- kernel: Driver service
- filesystem: File system driver service
- adapter: Adapter driver service (reserved)
- recognizer: Recognizer driver service (reserved)
- own (default): Service runs in its own process
- share: Service shares a process with one or more other services
start_type (str): Specifies the service start type. Valid options are as follows:
- boot: Device driver that is loaded by the boot loader
- system: Device driver that is started during kernel initialization
- auto: Service that automatically starts
- manual (default): Service must be started manually
- disabled: Service cannot be started
start_delayed (bool): Set the service to Auto(Delayed Start). Only valid if the start_type is set to
Auto
. If service_type is not passed, but the service is already set toAuto
, then the flag will be set. Default isFalse
error_control (str): The severity of the error, and action taken, if this service fails to start. Valid options are as follows:
- normal (normal): Error is logged and a message box is displayed
- severe: Error is logged and computer attempts a restart with the last known good configuration
- critical: Error is logged, computer attempts to restart with the last known good configuration, system halts on failure
- ignore: Error is logged and startup continues, no notification is given to the user
- load_order_group: The name of the load order group to which this service
- belongs
dependencies (list): A list of services or load ordering groups that must start before this service
account_name (str): The name of the account under which the service should run. For
own
type services this should be in thedomain\username
format. The following are examples of valid built-in service accounts:
- NT Authority\LocalService
- NT Authority\NetworkService
- NT Authority\LocalSystem
- .\LocalSystem
account_password (str): The password for the account name specified in
account_name
. For the above built-in accounts, this can be None. Otherwise a password must be specified.run_interactive (bool): If this setting is True, the service will be allowed to interact with the user. Not recommended for services that run with elevated privileges.
CLI Example:
salt '*' service.create <service name> <path to exe> display_name='<display name>'
salt.modules.win_service.
create_win_salt_restart_task
()¶Create a task in Windows task scheduler to enable restarting the salt-minion
CLI Example:
salt '*' service.create_win_salt_restart_task()
salt.modules.win_service.
delete
(name)¶Delete the named service
CLI Example:
salt '*' service.delete <service name>
salt.modules.win_service.
disable
(name, **kwargs)¶Disable the named service to start at boot
True
if disabled, False
otherwiseCLI Example:
salt '*' service.disable <service name>
salt.modules.win_service.
disabled
(name)¶Check to see if the named service is disabled to start on boot
CLI Example:
salt '*' service.disabled <service name>
salt.modules.win_service.
enable
(name, **kwargs)¶Enable the named service to start at boot
True
if successful, False
otherwiseCLI Example:
salt '*' service.enable <service name>
salt.modules.win_service.
enabled
(name, **kwargs)¶Check to see if the named service is enabled to start on boot
CLI Example:
salt '*' service.enabled <service name>
salt.modules.win_service.
execute_salt_restart_task
()¶Run the Windows Salt restart task
CLI Example:
salt '*' service.execute_salt_restart_task()
salt.modules.win_service.
get_all
()¶Return all installed services
CLI Example:
salt '*' service.get_all
salt.modules.win_service.
get_disabled
()¶Return a list of disabled services. Disabled is defined as a service that is marked 'Disabled' or 'Manual'.
CLI Example:
salt '*' service.get_disabled
salt.modules.win_service.
get_enabled
()¶Return a list of enabled services. Enabled is defined as a service that is marked to Auto Start.
CLI Example:
salt '*' service.get_enabled
salt.modules.win_service.
get_service_name
(*args)¶The Display Name is what is displayed in Windows when services.msc is executed. Each Display Name has an associated Service Name which is the actual name of the service. This function allows you to discover the Service Name by returning a dictionary of Display Names and Service Names, or filter by adding arguments of Display Names.
If no args are passed, return a dict of all services where the keys are the service Display Names and the values are the Service Names.
If arguments are passed, create a dict of Display Names and Service Names
CLI Examples:
salt '*' service.get_service_name
salt '*' service.get_service_name 'Google Update Service (gupdate)' 'DHCP Client'
salt.modules.win_service.
getsid
(name)¶Return the SID for this windows service
CLI Example:
salt '*' service.getsid <service name>
salt.modules.win_service.
info
(name)¶Get information about a service on the system
get_service_name
to find the service name.CLI Example:
salt '*' service.info spooler
salt.modules.win_service.
missing
(name)¶The inverse of service.available.
True
if the service is missing, False
otherwiseCLI Example:
salt '*' service.missing <service name>
salt.modules.win_service.
modify
(name, bin_path=None, exe_args=None, display_name=None, description=None, service_type=None, start_type=None, start_delayed=None, error_control=None, load_order_group=None, dependencies=None, account_name=None, account_password=None, run_interactive=None)¶Modify a service's parameters. Changes will not be made for parameters that are not passed.
New in version Carbon.
name (str): The name of the service. Can be found using the
service.get_service_name
function
bin_path (str): The path to the service executable. Backslashes must be escaped, eg: C:\path\to\binary.exe
exe_args (str): Any arguments required by the service executable
display_name (str): The name to display in the service manager
description (str): The description to display for the service
service_type (str): Specifies the service type. Default is own
.
Valid options are as follows:
- kernel: Driver service
- filesystem: File system driver service
- adapter: Adapter driver service (reserved)
- recognizer: Recognizer driver service (reserved)
- own (default): Service runs in its own process
- share: Service shares a process with one or more other services
start_delayed (bool): Set the service to Auto(Delayed Start). Only valid
if the start_type is set to Auto
. If service_type is not passed, but
the service is already set to Auto
, then the flag will be set.
error_control (str): The severity of the error, and action taken, if this service fails to start. Valid options are as follows:
- normal: Error is logged and a message box is displayed
- severe: Error is logged and computer attempts a restart with the last known good configuration
- critical: Error is logged, computer attempts to restart with the last known good configuration, system halts on failure
- ignore: Error is logged and startup continues, no notification is given to the user
dependencies (list): A list of services or load ordering groups that must start before this service
account_name (str): The name of the account under which the service
should run. For own
type services this should be in the
domain\username
format. The following are examples of valid built-in
service accounts:
- NT Authority\LocalService
- NT Authority\NetworkService
- NT Authority\LocalSystem
- .LocalSystem
account_password (str): The password for the account name specified in
account_name
. For the above built-in accounts, this can be None.
Otherwise a password must be specified.
run_interactive (bool): If this setting is True, the service will be allowed to interact with the user. Not recommended for services that run with elevated privileges.
salt.modules.win_service.
restart
(name)¶Restart the named service. This issues a stop command followed by a start.
Note
If the name passed is salt-minion
a scheduled task is created and
executed to restart the salt-minion service.
True
if successful, False
otherwiseCLI Example:
salt '*' service.restart <service name>
salt.modules.win_service.
start
(name)¶Start the specified service
CLI Example:
salt '*' service.start <service name>
salt.modules.win_service.
status
(name, sig=None)¶Return the status for a service
CLI Example:
salt '*' service.status <service name> [service signature]
salt.modules.win_service.
stop
(name)¶Stop the specified service
CLI Example:
salt '*' service.stop <service name>