ansible / ansible.windows / 2.3.0 / module / win_service Manage and query Windows services Authors: Chris Hoffman (@chrishoffman)ansible.windows.win_service (2.3.0) — module
Install with ansible-galaxy collection install ansible.windows:==2.3.0
collections: - name: ansible.windows version: 2.3.0
Manage and query Windows services.
For non-Windows targets, use the M(ansible.builtin.service) module instead.
- 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: true
- 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
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 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. - 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 should be supplied together when using a local or domain account. - If omitted then the password will continue to use the existing value password set. - If specifying C(LocalSystem), C(NetworkService), C(LocalService), the C(NT SERVICE), or a gMSA this field can be omitted as those accounts have no password. type: str sid_info: choices: - none - restricted - unrestricted description: - Used to define the behaviour of the service's access token groups. - C(none) will not add any groups to the token. - C(restricted) will add the C(NT SERVICE\<service name>) SID to the access token's groups and restricted groups. - C(unrestricted) will add the C(NT SERVICE\<service name>) SID to the access token's groups. type: str username: description: - The username to set the service to start as. - Can also be set to C(LocalSystem) or C(SYSTEM) 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(ansible.windows.win_user_right) module to grant this user right for you. - Set to C(NT SERVICE\service name) to run as the NT SERVICE account for that service. - This can also be a gMSA in the form C(DOMAIN\gMSA$). type: str start_mode: choices: - auto - delayed - disabled - manual description: - Set the startup type for the service. - A newly created service will default to C(auto). type: str description: description: - The description to set for the service. type: str 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. elements: str type: list display_name: description: - The display name to set for the service. type: str service_type: choices: - user_own_process - user_share_process - win32_own_process - win32_share_process description: - The type of service. - The default type of a new service is C(win32_own_process). - I(desktop_interact) can only be set if the service type is C(win32_own_process) or C(win32_share_process). type: str error_control: choices: - critical - ignore - normal - severe description: - The severity of the error and action token if the service fails to start. - A new service defaults to C(normal). - C(critical) will log the error and restart the system with the last-known good configuration. If the startup fails on reboot then the system will fail to operate. - C(ignore) ignores the error. - C(normal) logs the error in the event log but continues. - C(severe) is like C(critical) but a failure on the last-known good configuration reboot startup will be ignored. type: str failure_actions: description: - A list of failure actions the service controller should take on each failure of a service. - The service manager will run the actions from first to last defined until the service starts. If I(failure_reset_period_sec) has been exceeded then the failure actions will restart from the beginning. - If all actions have been performed the the service manager will repeat the last service defined. - The existing actions will be replaced with the list defined in the task if there is a mismatch with any of them. - Set to an empty list to delete all failure actions on a service otherwise an omitted or null value preserves the existing actions on the service. elements: dict suboptions: delay_ms: aliases: - delay default: 0 description: - The time to wait, in milliseconds, before performing the specified action. type: raw type: choices: - none - reboot - restart - run_command description: - The action to be performed. - C(none) will perform no action, when used this should only be set as the last action. - C(reboot) will reboot the host, when used this should only be set as the last action as the reboot will reset the action list back to the beginning. - C(restart) will restart the service. - C(run_command) will run the command specified by I(failure_command). required: true type: str type: list failure_command: description: - The command to run for a C(run_command) failure action. - Set to an empty string to remove the command. type: str update_password: choices: - always - on_create description: - When set to C(always) and I(password) is set, the module will always report a change and set the password. - Set to C(on_create) to only set the password if the module needs to create the service. - If I(username) was specified and the service changed to that username then I(password) will also be changed if specified. - The current default is C(on_create) but this behaviour may change in the future, it is best to be explicit here. type: str desktop_interact: default: false description: - Whether to allow the service user to interact with the desktop. - This can only be set to C(true) when using the C(LocalSystem) username. - This can only be set to C(true) when the I(service_type) is C(win32_own_process) or C(win32_share_process). type: bool load_order_group: description: - The name of the load ordering group of which this service is a member. - Specify an empty string to remove the existing load order group of a service. type: str 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 failure_reboot_msg: description: - The message to be broadcast to users logged on the host for a C(reboot) failure action. - Set to an empty string to remove the message. type: str required_privileges: description: - A list of privileges the service must have when starting up. - When set the service will only have the privileges specified on its access token. - The I(username) of the service must already have the privileges assigned. - The existing privileges will be replace with the list defined in the task if there is a mismatch with any of them. - Set to an empty list to remove all required privileges, otherwise an omitted or null value will keep the existing privileges. - See L(privilege text constants,https://docs.microsoft.com/en-us/windows/win32/secauthz/privilege-constants) for a list of privilege constants that can be used. elements: str type: list pre_shutdown_timeout_ms: aliases: - pre_shutdown_timeout description: - The time in which the service manager waits after sending a preshutdown notification to the service until it proceeds to continue with the other shutdown actions. type: raw failure_reset_period_sec: aliases: - failure_reset_period description: - The time in seconds after which the failure action list resets back to the start of the list if there are no failures. - To set this value, I(failure_actions) must have at least 1 action present. - Specify C('0xFFFFFFFF') to set an infinite reset period. type: raw force_dependent_services: default: false description: - If C(true), stopping or restarting a service with dependent services will force the dependent services to stop or restart also. - If C(false), stopping or restarting a service with dependent services may fail. type: bool failure_actions_on_non_crash_failure: description: - Controls whether failure actions will be performed on non crash failures or not. type: bool
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