ansible / ansible.builtin / v2.9.27 / module / win_service Manage and query Windows services | "added in version" 1.7 of ansible.builtin" Authors: Chris Hoffman (@chrishoffman) stableinterface | supported by coreansible.builtin.win_service (v2.9.27) — module
pip
Install with pip install ansible==2.9.27
Manage and query Windows services.
For non-Windows targets, use the M(service) module instead.
- 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
name: description: - 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. required: true type: str path: description: - The path to the executable to set for the service. type: str version_added: '2.3' version_added_collection: ansible.builtin state: choices: - absent - paused - started - stopped - restarted description: - The desired state of the service. - C(started)/C(stopped)/C(absent)/C(paused) are idempotent actions that will not run commands unless necessary. - C(restarted) will always bounce the service. - C(absent) was added in Ansible 2.3 - C(paused) 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. - A newly created service will default to C(stopped). type: str password: description: - The password to set the service to start as. - This and the C(username) argument must be supplied together. - If specifying C(LocalSystem), C(NetworkService) or C(LocalService) this field must be an empty string and not null. type: str 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 when using a local or domain account. - Set to C(LocalSystem) to use the SYSTEM account. - A newly created service will default to C(LocalSystem). - If using a custom user account, it must have the C(SeServiceLogonRight) granted to be able to start up. You can use the M(win_user_right) module to grant this user right for you. type: str version_added: '2.3' version_added_collection: ansible.builtin start_mode: choices: - auto - delayed - disabled - manual description: - Set the startup type for the service. - A newly created service will default to C(auto). - C(delayed) added in Ansible 2.3 type: str description: description: - The description to set for the service. type: str 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. type: list version_added: '2.3' version_added_collection: ansible.builtin display_name: description: - The display name to set for the service. type: str 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 C(yes) when using the C(LocalSystem) username. type: bool version_added: '2.3' version_added_collection: ansible.builtin dependency_action: choices: - add - remove - set 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. type: str version_added: '2.3' version_added_collection: ansible.builtin force_dependent_services: default: false description: - If C(yes), stopping or restarting a service with dependent services will force the dependent services to stop or restart also. - If C(no), stopping or restarting a service with dependent services may fail. type: bool version_added: '2.3' version_added_collection: ansible.builtin
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: str desktop_interact: description: Whether the current user is allowed to interact with the desktop. returned: success and service exists sample: false type: bool display_name: description: The display name of the installed service. returned: success and service exists sample: CoreMessaging type: str exists: description: Whether the service exists or not. returned: success sample: true type: bool name: description: The service name or id of the service. returned: success and service exists sample: CoreMessagingRegistrar type: str path: description: The path to the service executable. returned: success and service exists sample: C:\Windows\system32\svchost.exe -k LocalServiceNoNetwork type: str start_mode: description: The startup type of the service. returned: success and service exists sample: manual type: str state: description: The current running status of the service. returned: success and service exists sample: stopped type: str username: description: The username that runs the service. returned: success and service exists sample: LocalSystem type: str