ansible.windows.win_service – Manage and query Windows services

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

Synopsis

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

Parameters

Notes

See Also

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: yes

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

Authors

• Chris Hoffman (@chrishoffman)