diff --git a/lib/ansible/modules/windows/win_service.py b/lib/ansible/modules/windows/win_service.py index e91529f357d..4e73361eecb 100644 --- a/lib/ansible/modules/windows/win_service.py +++ b/lib/ansible/modules/windows/win_service.py @@ -11,11 +11,11 @@ ANSIBLE_METADATA = {'metadata_version': '1.1', DOCUMENTATION = r''' --- module: win_service -version_added: "1.7" +version_added: '1.7' short_description: Manage and query Windows services description: - - Manage and query Windows services. - - For non-Windows targets, use the M(service) module instead. +- Manage and query Windows services. +- For non-Windows targets, use the M(service) module instead. options: dependencies: description: @@ -25,7 +25,7 @@ options: - 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: '2.3' dependency_action: description: - Used in conjunction with C(dependency) to either add the dependencies to @@ -33,24 +33,27 @@ options: - Remove the dependencies to the existing dependencies. - Set the dependencies to only the values in the list replacing the existing dependencies. + type: str choices: [ add, remove, set ] default: set - version_added: "2.3" + version_added: '2.3' desktop_interact: description: - - Whether to allow the service user to interact with the desktop. - - This should only be set to C(yes) when using the LocalSystem username. + - 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 - default: 'no' - version_added: "2.3" + default: no + version_added: '2.3' description: description: - The description to set for the service. - version_added: "2.3" + type: str + version_added: '2.3' display_name: description: - The display name to set for the service. - version_added: "2.3" + type: str + version_added: '2.3' force_dependent_services: description: - If C(yes), stopping or restarting a service with dependent services will @@ -58,50 +61,55 @@ options: - If C(no), stopping or restarting a service with dependent services may fail. type: bool - default: 'no' - version_added: "2.3" + default: no + version_added: '2.3' 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. + - 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: yes + type: str path: description: - - The path to the executable to set for the service. - version_added: "2.3" + - The path to the executable to set for the service. + version_added: '2.3' 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" + - 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. + version_added: '2.3' start_mode: description: - - Set the startup type for the service. - - C(delayed) added in Ansible 2.3 + - Set the startup type for the service. + - A newly created service will default to C(auto). + - C(delayed) added in Ansible 2.3 choices: [ auto, delayed, disabled, manual ] state: 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. + - 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). choices: [ absent, paused, started, stopped, restarted ] 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. - version_added: "2.3" + - 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). + version_added: '2.3' notes: - - For non-Windows targets, use the M(service) module instead. +- For non-Windows targets, use the M(service) module instead. author: - Chris Hoffman (@chrishoffman) ''' @@ -123,7 +131,12 @@ EXAMPLES = r''' name: Netlogon state: paused -# a new service will also default to the following values: +- 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 @@ -168,7 +181,7 @@ EXAMPLES = r''' name: service name state: restarted username: LocalSystem - password: "" + password: '' - name: Set the log on user to Local System and allow it to interact with the desktop win_service: @@ -183,30 +196,32 @@ EXAMPLES = r''' name: service name state: restarted username: NT AUTHORITY\NetworkService - password: "" + password: '' - name: Set the log on user to Local Service win_service: name: service name state: restarted username: NT AUTHORITY\LocalService - password: "" + password: '' - name: Set dependencies to ones only in the list win_service: name: service name - dependencies: ['service1', 'service2'] + dependencies: [ service1, service2 ] - name: Add dependencies to existing dependencies win_service: name: service name - dependencies: ['service1', 'service2'] + dependencies: [ service1, service2 ] dependency_action: add - name: Remove dependencies from existing dependencies win_service: name: service name - dependencies: ['service1', 'service2'] + dependencies: + - service1 + - service2 dependency_action: remove '''