win_service – Manage and query Windows services — Ansible Documentation

- AnsibleFest
- Products
- Community
- Webinars & Training
- Blog

Documentation

# 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 | Choices: 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 | Choices: 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 | Choices: 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 | Choices: 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 | Choices: 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.