Docs: Clean up 'win_service' module docs (#46407)
* Docs: Clean up 'win_service' module docs This is part of a series of module doc cleanups. * Fix typo pause vs paused * Use both YAML list syntaxes
This commit is contained in:
Dag Wieers
Jordan Borean
parent
069ba81386
commit
3f2f53681d
1 changed files with 61 additions and 46 deletions
|
|
@ -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
|
||||
'''
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue