Windows Service module.
Changed in version 2016.11.0: Rewritten to use PyWin32
Check if a service is available on the system.
name (str) -- The name of the service to check
True
if the service is available, False
otherwise
CLI Example:
salt '*' service.available <service name>
Create the named service.
New in version 2015.8.0.
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
, optional) --
Any additional arguments required by the service binary.
Default is None
.
display_name (str
, optional) --
The name to be displayed in the service manager. If not passed, the
name
will be used.
Default is None
.
description (str
, optional) --
A description of the service.
Default is None
.
service_type (str
, optional) --
Specifies the service type. 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
Default is "own".
start_type (str
, optional) --
Specifies the service start type. Valid options are as follows:
boot: Device driver that is loaded by the bootloader
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
Default is "manual".
start_delayed (bool
, optional) --
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.
Default is
False
.
error_control (str
, optional) --
The severity of the error, and action taken, if this service fails to start. Valid options are as follows:
normal (default): 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
Default is "normal".
load_order_group (str
, optional) --
The name of the load order group to which this service belongs.
Default is None
.
dependencies (list
, optional) --
A list of services or load ordering groups that must start before this service.
Default is None
.
account_name (str
, optional) --
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 AuthorityLocalService
NT AuthorityNetworkService
NT AuthorityLocalSystem
.LocalSystem
Default is \LocalSystem
.
account_password (str
, optional) --
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.
Default is None
.
run_interactive (bool
, optional) --
If this setting is True
, the service will be allowed to interact
with the user. Not recommended for services that run with elevated
privileges.
Default is False
.
A dictionary containing information about the new service
CLI Example:
salt '*' service.create <service name> <path to exe> display_name='<display name>'
Create a task in Windows task scheduler to enable restarting the salt-minion
True
if successful, otherwise False
CLI Example:
salt '*' service.create_win_salt_restart_task()
Delete the named service
True
if successful, otherwise False
. Also returns True
if the service is not present
CLI Example:
salt '*' service.delete <service name>
Disable the named service to start at boot
name (str) -- The name of the service to disable.
True
if disabled, otherwise False
CLI Example:
salt '*' service.disable <service name>
Check to see if the named service is disabled to start on boot
name (str) -- The name of the service to check
True
if the service is disabled, otherwise False
CLI Example:
salt '*' service.disabled <service name>
Enable the named service to start at boot
name (str) -- The name of the service to enable.
start_type (str
, optional) --
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: Service must be started manually
disabled: Service cannot be started
Default is "auto".
start_delayed (bool
, optional) --
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.
Default is False
.
True
if successful, otherwise False
CLI Example:
salt '*' service.enable <service name>
Check to see if the named service is enabled to start on boot
name (str) -- The name of the service to check
True
if the service is set to start, otherwise False
CLI Example:
salt '*' service.enabled <service name>
Run the Windows Salt restart task
True
if successful, otherwise False
CLI Example:
salt '*' service.execute_salt_restart_task()
Return all installed services
Returns a list of all services on the system.
CLI Example:
salt '*' service.get_all
Return a list of disabled services. Disabled is defined as a service that is marked 'Disabled' or 'Manual'.
A list of disabled services.
CLI Example:
salt '*' service.get_disabled
Return a list of enabled services. Enabled is defined as a service that is marked to Auto Start.
A list of enabled services
CLI Example:
salt '*' service.get_enabled
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
A dictionary of display names and service names
CLI Examples:
salt '*' service.get_service_name
salt '*' service.get_service_name 'Google Update Service (gupdate)' 'DHCP Client'
Return the SID for this windows service
name (str) -- The name of the service for which to return the SID
A string representing the SID for the service
CLI Example:
salt '*' service.getsid <service name>
Get information about a service on the system
name (str) -- The name of the service. This is not the display name. Use
get_service_name
to find the service name.
A dictionary containing information about the service.
CLI Example:
salt '*' service.info spooler
The inverse of service.available.
name (str) -- The name of the service to check
True
if the service is missing, False
otherwise
CLI Example:
salt '*' service.missing <service name>
Modify a service's parameters. Changes will not be made for parameters that are not passed.
New in version 2016.11.0.
name (str) -- The name of the service. Can be found using the
service.get_service_name
function.
bin_path (str
, optional) --
The path to the service executable. Backslashes must be escaped, eg:
C:\path\to\binary.exe
.
Default is None
.
exe_args (str
, optional) --
Any arguments required by the service executable.
Default is None
.
display_name (str
, optional) --
The name to display in the service manager.
Default is None
.
description (str
, optional) --
The description to display for the service.
Default is None
.
service_type (str
, optional) --
Specifies the service type. None
defaults to 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
Default is None
.
start_type (str
, optional) --
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: Service must be started manually
disabled: Service cannot be started
Default is None
.
start_delayed (bool
, optional) --
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.
Default is None
.
error_control (str
, optional) --
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
Default is None
.
load_order_group (str
, optional) --
The name of the load order group to which this service belongs.
Default is None
.
dependencies (list
, optional) --
A list of services or load ordering groups that must start before this service.
Default is None
.
account_name (str
, optional) --
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 AuthorityLocalService
NT AuthorityNetworkService
NT AuthorityLocalSystem
.LocalSystem
Default is None
.
account_password (str
, optional) --
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.
Default is None
.
run_interactive (bool
, optional) --
If this setting is True, the service will be allowed to interact with the user. Not recommended for services that run with elevated privileges.
Default is None
.
a dictionary of changes made
CLI Example:
salt '*' service.modify spooler start_type=disabled
Restart the named service. This issues a stop command followed by a start.
name --
The name of the service to restart.
Note
If the name passed is salt-minion
a scheduled task is
created and executed to restart the salt-minion service.
timeout (int
, optional) --
The time in seconds to wait for the service to stop and start before returning.
Note
The timeout is cumulative meaning it is applied to the stop and then to the start command. A timeout of 90 could take up to 180 seconds if the service is long in stopping and starting
New in version 2017.7.9,2018.3.4.
Default is 90 seconds.
True
if successful, otherwise False
CLI Example:
salt '*' service.restart <service name>
Start the specified service.
Warning
You cannot start a disabled service in Windows. If the service is
disabled, it will be changed to Manual
start.
True
if successful, otherwise False
. Also returns True
if the service is already started
CLI Example:
salt '*' service.start <service name>
Return the status for a service. If the name contains globbing, a dict mapping service name to True/False values is returned.
Changed in version 2018.3.0: The service name can now be a glob (e.g. salt*
)
Changed in version 3006.0: Returns "Not Found" if the service is not found on the system
name (str) -- The name of the service to check
True if running, False otherwise dict: Maps service name to True if running, False otherwise str: Not Found if the service is not found on the system
CLI Example:
salt '*' service.status <service name>
Stop the specified service
True
if successful, otherwise False
. Also returns True
if the service is already stopped
CLI Example:
salt '*' service.stop <service name>