win_service – Manage and query Windows services

win_service – Manage and query Windows services

• Synopsis
• Parameters
• See Also
• Examples
• Return Values
• Status

Synopsis

• Manage and query Windows services.
• For non-Windows targets, use the service module instead.

Parameters

Parameter	Choices/Defaults	Comments
dependencies list		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 to either add/remove or set the services in this list.
dependency_action string	add remove set ←	Used in conjunction with dependency to either add the dependencies to the existing service dependencies. Remove the dependencies to the existing dependencies. Set the dependencies to only the values in the list replacing the existing dependencies.
description string		The description to set for the service.
desktop_interact boolean	no ← yes	Whether to allow the service user to interact with the desktop. This should only be set to yes when using the LocalSystem username.
display_name string		The display name to set for the service.
force_dependent_services boolean	no ← yes	If yes, stopping or restarting a service with dependent services will force the dependent services to stop or restart also. If no, stopping or restarting a service with dependent services may fail.
name string / 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 string		The password to set the service to start as. This and the username argument must be supplied together. If specifying LocalSystem, NetworkService or LocalService this field must be an empty string and not null.
path string		The path to the executable to set for the service.
start_mode string	auto delayed disabled manual	Set the startup type for the service. A newly created service will default to auto. delayed added in Ansible 2.3
state string	absent paused started stopped restarted	The desired state of the service. started/stopped/absent/paused are idempotent actions that will not run commands unless necessary. restarted will always bounce the service. absent was added in Ansible 2.3 paused was added in Ansible 2.4 Only services that support the paused state can be paused, you can check the return value can_pause_and_continue. You can only pause a service that is already started. A newly created service will default to stopped.
username string		The username to set the service to start as. This and the password argument must be supplied together when using a local or domain account. Set to LocalSystem to use the SYSTEM account. A newly created service will default to LocalSystem. If using a custom user account, it must have the SeServiceLogonRight granted to be able to start up. You can use the win_user_right module to grant this user right for you.

See Also

See also

service – Manage services

The official documentation on the service module.

win_nssm – Install a service using NSSM

The official documentation on the win_nssm module.

win_user_right – Manage Windows User Rights

The official documentation on the win_user_right module.

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

- name: Ensure that WinRM is started when the system has settled
  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
  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

# 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
  win_user_right:
    name: SeServiceLogonRight
    users:
    - DOMAIN\User
    action: add

- 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 backward compatible 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)

Hint

If you notice any issues in this documentation, you can edit this document to improve it.

© 2012–2018 Michael DeHaan
© 2018–2019 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.9/modules/win_service_module.html