Documentation

win_service - Manages Windows services

New in version 1.7.

Synopsis

  • Manages Windows services

Options

parameter required default choices comments
dependencies
(added in 2.3)
no
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
(added in 2.3)
no set
  • set
  • add
  • remove
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
(added in 2.3)
no
The description to set for the service.
desktop_interact
(added in 2.3)
no
Whether to allow the service user to interact with the desktop.
This should only be set to true when using the LocalSystem username.
display_name
(added in 2.3)
no
The display name to set for the service.
force_dependent_services
(added in 2.3)
no
If True, stopping or restarting a service with dependent services will force the dependent services to stop or restart also.
If False, stopping or restarting a service with dependent services may fail.
name
yes
Name of the service
password
(added in 2.3)
no
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
(added in 2.3)
no
The path to the executable to set for the service.
start_mode
no
  • auto
  • manual
  • disabled
  • delayed
Set the startup type for the service.
delayed added in Ansible 2.3
state
no
  • started
  • stopped
  • restarted
  • absent
started/stopped/absent are idempotent actions that will not run commands unless necessary.
restarted will always bounce the service.
absent added in Ansible 2.3
username
(added in 2.3)
no
The username to set the service to start as.
This and the password argument must be supplied together.

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

# 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: True

- 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 Return Values, the following are the fields unique to this module:

name description returned type sample
status the current running status of the service success and service exists string stopped
username the username that runs the service success and service exists string LocalSystem
display_name the display name of the installed service success and service exists string CoreMessaging
name the service name or id of the service success and service exists string CoreMessagingRegistrar
exists whether the service exists or not success boolean True
start_mode the startup type of the service success and service exists string manual
description the path to the executable of the service success and service exists string Manages communication between system components.
depended_by A list of dependencies this service relies on success and service exists list False
dependencies A list of dependencies the service relies on success and service exists list False
path path to the service success and service exists string C:\Windows\system32\svchost.exe -k LocalServiceNoNetwork
desktop_interact Whether the current user is allowed to interact with the desktop success and service exists boolean False


Status

This module is flagged as stableinterface which means that the maintainers for this module guarantee that no backward incompatible interface changes will be made.

Support

This module is maintained by those with core commit privileges

For more information on what this means please read Module Support

For help in developing on modules, should you be so inclined, please read Community Information & Contributing, Testing Ansible and Developing Modules.