ansible.builtin.win_service (v2.4.3.0-1) — module

Install Ansible via pip

Install with pip install ansible==2.4.3.0.post1

Description

Manages Windows services.

For non-Windows targets, use the M(service) module instead.

Usage examples

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

- name: Restart a service
  win_service:
    name: spooler
    state: restarted

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

- name: Set service startup mode to auto and ensure it is started
  win_service:
    name: spooler
    start_mode: auto
    state: started

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

- name: pause a service
  win_service:
    name: Netlogon
    state: paused

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

# 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

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

- 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

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

- name: remove a service
  win_service:
    name: service name
    state: absent

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

- name: check if a service is installed
  win_service:
    name: service name
  register: service_info

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

- name: set the log on user to a domain account
  win_service:
    name: service name
    state: restarted
    username: DOMAIN\User
    password: Password

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

- name: set the log on user to a local account
  win_service:
    name: service name
    state: restarted
    username: .\Administrator
    password: Password

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

- name: set the log on user to Local System
  win_service:
    name: service name
    state: restarted
    username: LocalSystem
    password: ""

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

- 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

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

- name: set the log on user to Network Service
  win_service:
    name: service name
    state: restarted
    username: NT AUTHORITY\NetworkService
    password: ""

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

- name: set the log on user to Local Service
  win_service:
    name: service name
    state: restarted
    username: NT AUTHORITY\LocalService
    password: ""

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

- name: set dependencies to ones only in the list
  win_service:
    name: service name
    dependencies: ['service1', 'service2']

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

- name: add dependencies to existing dependencies
  win_service:
    name: service name
    dependencies: ['service1', 'service2']
    dependency_action: add

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

- name: remove dependencies from existing dependencies
  win_service:
    name: service name
    dependencies: ['service1', 'service2']
    dependency_action: remove

Inputs

    
name:
    description:
    - Name of the service
    required: true

path:
    description:
    - The path to the executable to set for the service.
    version_added: '2.3'
    version_added_collection: ansible.builtin

state:
    choices:
    - started
    - stopped
    - restarted
    - absent
    - paused
    description:
    - C(started)/C(stopped)/C(absent)/C(pause) are idempotent actions that will not run
      commands unless necessary.
    - C(restarted) will always bounce the service.
    - C(absent) added in Ansible 2.3
    - C(pause) was added in Ansible 2.4
    - Only services that support the paused state can be paused, you can check the return
      value C(can_pause_and_continue).
    - You can only pause a service that is already started.

password:
    description:
    - The password to set the service to start as.
    - This and the C(username) argument must be supplied together.
    - If specifying LocalSystem, NetworkService or LocalService this field must be an
      empty string and not null.
    version_added: '2.3'
    version_added_collection: ansible.builtin

username:
    description:
    - The username to set the service to start as.
    - This and the C(password) argument must be supplied together.
    version_added: '2.3'
    version_added_collection: ansible.builtin

start_mode:
    choices:
    - auto
    - manual
    - disabled
    - delayed
    description:
    - Set the startup type for the service.
    - C(delayed) added in Ansible 2.3

description:
    description:
    - The description to set for the service.
    version_added: '2.3'
    version_added_collection: ansible.builtin

dependencies:
    description:
    - 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 C(dependency_action) to either add/remove or set the services in this
      list.
    version_added: '2.3'
    version_added_collection: ansible.builtin

display_name:
    description:
    - The display name to set for the service.
    version_added: '2.3'
    version_added_collection: ansible.builtin

desktop_interact:
    default: false
    description:
    - Whether to allow the service user to interact with the desktop.
    - This should only be set to true when using the LocalSystem username.
    version_added: '2.3'
    version_added_collection: ansible.builtin

dependency_action:
    choices:
    - set
    - add
    - remove
    default: set
    description:
    - Used in conjunction with C(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.
    version_added: '2.3'
    version_added_collection: ansible.builtin

force_dependent_services:
    default: false
    description:
    - 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.
    version_added: '2.3'
    version_added_collection: ansible.builtin

Outputs

can_pause_and_continue:
  description: Whether the service can be paused and unpaused.
  returned: success and service exists
  sample: true
  type: bool
depended_by:
  description: A list of services that depend on this service.
  returned: success and service exists
  sample: false
  type: list
dependencies:
  description: A list of services that is depended by this service.
  returned: success and service exists
  sample: false
  type: list
description:
  description: The description of the service.
  returned: success and service exists
  sample: Manages communication between system components.
  type: string
desktop_interact:
  description: Whether the current user is allowed to interact with the desktop.
  returned: success and service exists
  sample: false
  type: boolean
display_name:
  description: The display name of the installed service.
  returned: success and service exists
  sample: CoreMessaging
  type: string
exists:
  description: Whether the service exists or not.
  returned: success
  sample: true
  type: boolean
name:
  description: The service name or id of the service.
  returned: success and service exists
  sample: CoreMessagingRegistrar
  type: string
path:
  description: The path to the service executable.
  returned: success and service exists
  sample: C:\Windows\system32\svchost.exe -k LocalServiceNoNetwork
  type: string
start_mode:
  description: The startup type of the service.
  returned: success and service exists
  sample: manual
  type: string
state:
  description: The current running status of the service.
  returned: success and service exists
  sample: stopped
  type: string
username:
  description: The username that runs the service.
  returned: success and service exists
  sample: LocalSystem
  type: string