win_service – Manage and query Windows services
win_service – Manage and query Windows services
New in version 1.7.
Synopsis
- Manage and query Windows services.
- For non-Windows targets, use the service module instead.
Parameters
Parameter | Choices/Defaults | Comments |
---|---|---|
dependencies list added in 2.3 |
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 | |
dependency_action - added in 2.3 |
|
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. |
description - added in 2.3 |
The description to set for the service. | |
desktop_interact boolean added in 2.3 |
|
Whether to allow the service user to interact with the desktop. This should only be set to |
display_name - added in 2.3 |
The display name to set for the service. | |
force_dependent_services boolean added in 2.3 |
|
If If |
name - / required |
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. | |
password - added in 2.3 |
The password to set the service to start as. This and the If specifying LocalSystem, NetworkService or LocalService this field must be an empty string and not null. | |
path - added in 2.3 |
The path to the executable to set for the service. | |
start_mode - |
|
Set the startup type for the service.
|
state - |
|
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. |
username - added in 2.3 |
The username to set the service to start as. This and the Set to |
Notes
Examples
- name: Restart a service
win_service:
name: spooler
state: restarted
- name: Set service startup mode to auto and ensure it is started
win_service:
name: spooler
start_mode: auto
state: started
- name: Pause a service
win_service:
name: Netlogon
state: paused
# a new service will also default to the following values:
# - username: LocalSystem
# - state: stopped
# - start_mode: auto
- name: Create a new service
win_service:
name: service name
path: C:\temp\test.exe
- name: Create a new service with extra details
win_service:
name: service name
path: C:\temp\test.exe
display_name: Service Name
description: A test service description
- name: Remove a service
win_service:
name: service name
state: absent
- name: Check if a service is installed
win_service:
name: service name
register: service_info
- name: Set the log on user to a domain account
win_service:
name: service name
state: restarted
username: DOMAIN\User
password: Password
- name: Set the log on user to a local account
win_service:
name: service name
state: restarted
username: .\Administrator
password: Password
- name: Set the log on user to Local System
win_service:
name: service name
state: restarted
username: LocalSystem
password: ""
- name: Set the log on user to Local System and allow it to interact with the desktop
win_service:
name: service name
state: restarted
username: LocalSystem
password: ""
desktop_interact: yes
- name: Set the log on user to Network Service
win_service:
name: service name
state: restarted
username: NT AUTHORITY\NetworkService
password: ""
- name: Set the log on user to Local Service
win_service:
name: service name
state: restarted
username: NT AUTHORITY\LocalService
password: ""
- name: Set dependencies to ones only in the list
win_service:
name: service name
dependencies: ['service1', 'service2']
- name: Add dependencies to existing dependencies
win_service:
name: service name
dependencies: ['service1', 'service2']
dependency_action: add
- name: Remove dependencies from existing dependencies
win_service:
name: service name
dependencies: ['service1', 'service2']
dependency_action: remove
Return Values
Common return values are documented here, the following are the fields unique to this module:
Key | Returned | Description |
---|---|---|
can_pause_and_continue boolean |
success and service exists |
Whether the service can be paused and unpaused.
Sample: True |
depended_by list |
success and service exists |
A list of services that depend on this service.
|
dependencies list |
success and service exists |
A list of services that is depended by this service.
|
description string |
success and service exists |
The description of the service.
Sample: Manages communication between system components. |
desktop_interact boolean |
success and service exists |
Whether the current user is allowed to interact with the desktop.
|
display_name string |
success and service exists |
The display name of the installed service.
Sample: CoreMessaging |
exists boolean |
success |
Whether the service exists or not.
Sample: True |
name string |
success and service exists |
The service name or id of the service.
Sample: CoreMessagingRegistrar |
path string |
success and service exists |
The path to the service executable.
Sample: C:\Windows\system32\svchost.exe -k LocalServiceNoNetwork |
start_mode string |
success and service exists |
The startup type of the service.
Sample: manual |
state string |
success and service exists |
The current running status of the service.
Sample: stopped |
username string |
success and service exists |
The username that runs the service.
Sample: LocalSystem |
Status
- This module is guaranteed to have no backward incompatible interface changes going forward. [stableinterface]
- This module is maintained by the Ansible Core Team. [core]
Red Hat Support
More information about Red Hat’s support of this module is available from this Red Hat Knowledge Base article.
Authors
- Chris Hoffman (@chrishoffman)
© 2012–2018 Michael DeHaan
© 2018–2019 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.7/modules/win_service_module.html