ansible.windows.win_service module – Manage and query Windows services
Note
This module is part of the ansible.windows collection (version 2.5.0).
You might already have this collection installed if you are using the ansible
package.
It is not included in ansible-core
.
To check whether it is installed, run ansible-galaxy collection list
.
To install it, use: ansible-galaxy collection install ansible.windows
.
To use it in a playbook, specify: ansible.windows.win_service
.
Synopsis
Manage and query Windows services.
For non-Windows targets, use the ansible.builtin.service module instead.
Parameters
Parameter |
Comments |
---|---|
A list of service dependencies to set for this particular service. This should be a list of service names and not the display name of the service. This works by |
|
Used in conjunction with Remove the dependencies to the existing dependencies. Set the dependencies to only the values in the list replacing the existing dependencies. Choices:
|
|
The description to set for the service. |
|
Whether to allow the service user to interact with the desktop. This can only be set to This can only be set to Choices:
|
|
The display name to set for the service. |
|
The severity of the error and action token if the service fails to start. A new service defaults to
Choices:
|
|
A list of failure actions the service controller should take on each failure of a service. The service manager will run the actions from first to last defined until the service starts. If failure_reset_period_sec has been exceeded then the failure actions will restart from the beginning. If all actions have been performed the the service manager will repeat the last service defined. The existing actions will be replaced with the list defined in the task if there is a mismatch with any of them. Set to an empty list to delete all failure actions on a service otherwise an omitted or null value preserves the existing actions on the service. |
|
The time to wait, in milliseconds, before performing the specified action. Default: |
|
The action to be performed.
Choices:
|
|
Controls whether failure actions will be performed on non crash failures or not. Choices:
|
|
The command to run for a Set to an empty string to remove the command. |
|
The message to be broadcast to users logged on the host for a Set to an empty string to remove the message. |
|
The time in seconds after which the failure action list resets back to the start of the list if there are no failures. To set this value, failure_actions must have at least 1 action present. Specify |
|
If If Choices:
|
|
The name of the load ordering group of which this service is a member. Specify an empty string to remove the existing load order group of a service. |
|
Name of the service. If only the name parameter is specified, the module will report on whether the service exists or not without making any changes. |
|
The password to set the service to start as. This and the If omitted then the password will continue to use the existing value password set. If specifying |
|
The path to the executable to set for the service. |
|
The time in which the service manager waits after sending a preshutdown notification to the service until it proceeds to continue with the other shutdown actions. |
|
A list of privileges the service must have when starting up. When set the service will only have the privileges specified on its access token. The username of the service must already have the privileges assigned. The existing privileges will be replace with the list defined in the task if there is a mismatch with any of them. Set to an empty list to remove all required privileges, otherwise an omitted or null value will keep the existing privileges. See privilege text constants for a list of privilege constants that can be used. |
|
The type of service. The default type of a new service is desktop_interact can only be set if the service type is Choices:
|
|
Used to define the behaviour of the service’s access token groups.
Choices:
|
|
Set the startup type for the service. A newly created service will default to Choices:
|
|
The desired state of the service.
Only services that support the paused state can be paused, you can check the return value You can only pause a service that is already started. A newly created service will default to Choices:
|
|
When set to Set to If username was specified and the service changed to that username then password will also be changed if specified. The current default is Choices:
|
|
The username to set the service to start as. Can also be set to A newly created service will default to If using a custom user account, it must have the Set to This can also be a gMSA in the form |
Notes
Note
This module historically returning information about the service in its return values. These should be avoided in favour of the ansible.windows.win_service_info module.
Most of the options in this module are non-driver services that you can view in SCManager. While you can edit driver services, not all functionality may be available.
The user running the module must have the following access rights on the service to be able to use it with this module -
SERVICE_CHANGE_CONFIG
,SERVICE_ENUMERATE_DEPENDENTS
,SERVICE_QUERY_CONFIG
,SERVICE_QUERY_STATUS
.Changing the state or removing the service will also require futher rights depending on what needs to be done.
See Also
See also
- ansible.builtin.service
Manage services.
- community.windows.win_nssm
Install a service using NSSM.
- ansible.windows.win_service_info
Gather information about Windows services.
- ansible.windows.win_user_right
Manage Windows User Rights.
Examples
- name: Restart a service
ansible.windows.win_service:
name: spooler
state: restarted
- name: Set service startup mode to auto and ensure it is started
ansible.windows.win_service:
name: spooler
start_mode: auto
state: started
- name: Pause a service
ansible.windows.win_service:
name: Netlogon
state: paused
- name: Ensure that WinRM is started when the system has settled
ansible.windows.win_service:
name: WinRM
start_mode: delayed
# A new service will also default to the following values:
# - username: LocalSystem
# - state: stopped
# - start_mode: auto
- name: Create a new service
ansible.windows.win_service:
name: service name
path: C:\temp\test.exe
- name: Create a new service with extra details
ansible.windows.win_service:
name: service name
path: C:\temp\test.exe
display_name: Service Name
description: A test service description
- name: Remove a service
ansible.windows.win_service:
name: service name
state: absent
# This is required to be set for non-service accounts that need to run as a service
- name: Grant domain account the SeServiceLogonRight user right
ansible.windows.win_user_right:
name: SeServiceLogonRight
users:
- DOMAIN\User
action: add
- name: Set the log on user to a domain account
ansible.windows.win_service:
name: service name
state: restarted
username: DOMAIN\User
password: Password
- name: Set the log on user to a local account
ansible.windows.win_service:
name: service name
state: restarted
username: .\Administrator
password: Password
- name: Set the log on user to Local System
ansible.windows.win_service:
name: service name
state: restarted
username: SYSTEM
- name: Set the log on user to Local System and allow it to interact with the desktop
ansible.windows.win_service:
name: service name
state: restarted
username: SYSTEM
desktop_interact: true
- name: Set the log on user to Network Service
ansible.windows.win_service:
name: service name
state: restarted
username: NT AUTHORITY\NetworkService
- name: Set the log on user to Local Service
ansible.windows.win_service:
name: service name
state: restarted
username: NT AUTHORITY\LocalService
- name: Set the log on user as the services' virtual account
ansible.windows.win_service:
name: service name
username: NT SERVICE\service name
- name: Set the log on user as a gMSA
ansible.windows.win_service:
name: service name
username: DOMAIN\gMSA$ # The end $ is important and should be set for all gMSA
- name: Set dependencies to ones only in the list
ansible.windows.win_service:
name: service name
dependencies: [service1, service2]
- name: Add dependencies to existing dependencies
ansible.windows.win_service:
name: service name
dependencies: [service1, service2]
dependency_action: add
- name: Remove dependencies from existing dependencies
ansible.windows.win_service:
name: service name
dependencies:
- service1
- service2
dependency_action: remove
- name: Set required privileges for a service
ansible.windows.win_service:
name: service name
username: NT SERVICE\LocalService
required_privileges:
- SeBackupPrivilege
- SeRestorePrivilege
- name: Remove all required privileges for a service
ansible.windows.win_service:
name: service name
username: NT SERVICE\LocalService
required_privileges: []
- name: Set failure actions for a service with no reset period
ansible.windows.win_service:
name: service name
failure_actions:
- type: restart
- type: run_command
delay_ms: 1000
- type: restart
delay_ms: 5000
- type: reboot
failure_command: C:\Windows\System32\cmd.exe /c mkdir C:\temp
failure_reboot_msg: Restarting host because service name has failed
failure_reset_period_sec: '0xFFFFFFFF'
- name: Set only 1 failure action without a repeat of the last action
ansible.windows.win_service:
name: service name
failure_actions:
- type: restart
delay_ms: 5000
- type: none
- name: Remove failure action information
ansible.windows.win_service:
name: service name
failure_actions: []
failure_command: '' # removes the existing command
failure_reboot_msg: '' # removes the existing reboot msg
Return Values
Common return values are documented here, the following are the fields unique to this module:
Key |
Description |
---|---|
Whether the service can be paused and unpaused. Returned: success and service exists Sample: |
|
A list of services that depend on this service. Returned: success and service exists Sample: |
|
A list of services that is depended by this service. Returned: success and service exists Sample: |
|
The description of the service. Returned: success and service exists Sample: |
|
Whether the current user is allowed to interact with the desktop. Returned: success and service exists Sample: |
|
The display name of the installed service. Returned: success and service exists Sample: |
|
Whether the service exists or not. Returned: success Sample: |
|
The service name or id of the service. Returned: success and service exists Sample: |
|
The path to the service executable. Returned: success and service exists Sample: |
|
The startup type of the service. Returned: success and service exists Sample: |
|
The current running status of the service. Returned: success and service exists Sample: |
|
The username that runs the service. Returned: success and service exists Sample: |