archive
/
ansible
mirror of https://github.com/ansible/ansible.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Documentation: fix formatting (#73186)

Browse Source
pull/73473/head
Andrew Klychkov 4 years ago committed by GitHub
parent dcec0ec806
commit 6cde1cdf35
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
10 changed files with 110 additions and 106 deletions
Show Stats Download Patch File Download Diff File

41
lib/ansible/modules/command.py
Unescape Escape View File

@ -45,7 +45,7 @@ options:
creates: creates:
type: path type: path
description: description:
- A filename or (since 2.0) glob pattern. If a matching file already exists, this step B(won't) be run. - A filename or (since 2.0) glob pattern. If a matching file already exists, this step B(will not) be run.
removes: removes:
type: path type: path
description: description:
@ -79,11 +79,12 @@ options:
type: bool type: bool
default: yes default: yes
notes: notes:
- If you want to run a command through the shell (say you are using C(<), C(>), C(|), etc), you actually want the M(ansible.builtin.shell) module instead. - If you want to run a command through the shell (say you are using C(<), C(>), C(|), and so on),
you actually want the M(ansible.builtin.shell) module instead.
Parsing shell metacharacters can lead to unexpected commands being executed if quoting is not done correctly so it is more secure to Parsing shell metacharacters can lead to unexpected commands being executed if quoting is not done correctly so it is more secure to
use the C(command) module when possible. use the C(command) module when possible.
- " C(creates), C(removes), and C(chdir) can be specified after the command. - C(creates), C(removes), and C(chdir) can be specified after the command.
For instance, if you only want to run a command if a certain file does not exist, use this." For instance, if you only want to run a command if a certain file does not exist, use this.
- Check mode is supported when passing C(creates) or C(removes). If running in check mode and either of these are specified, the module will - Check mode is supported when passing C(creates) or C(removes). If running in check mode and either of these are specified, the module will
check for the existence of the file and report the correct changed status. If these are not supplied, the task will be skipped. check for the existence of the file and report the correct changed status. If these are not supplied, the task will be skipped.
- The C(executable) parameter is removed since version 2.4. If you have a need for this parameter, use the M(ansible.builtin.shell) module instead. - The C(executable) parameter is removed since version 2.4. If you have a need for this parameter, use the M(ansible.builtin.shell) module instead.
@ -101,28 +102,28 @@ author:
EXAMPLES = r''' EXAMPLES = r'''
- name: Return motd to registered var - name: Return motd to registered var
command: cat /etc/motd ansible.builtin.command: cat /etc/motd
register: mymotd register: mymotd
# free-form (string) arguments, all arguments on one line # free-form (string) arguments, all arguments on one line
- name: Run command if /path/to/database does not exist (without 'args') - name: Run command if /path/to/database does not exist (without 'args')
command: /usr/bin/make_database.sh db_user db_name creates=/path/to/database ansible.builtin.command: /usr/bin/make_database.sh db_user db_name creates=/path/to/database
# free-form (string) arguments, some arguments on separate lines with the 'args' keyword # free-form (string) arguments, some arguments on separate lines with the 'args' keyword
# 'args' is a task keyword, passed at the same level as the module # 'args' is a task keyword, passed at the same level as the module
- name: Run command if /path/to/database does not exist (with 'args' keyword) - name: Run command if /path/to/database does not exist (with 'args' keyword)
command: /usr/bin/make_database.sh db_user db_name ansible.builtin.command: /usr/bin/make_database.sh db_user db_name
args: args:
creates: /path/to/database creates: /path/to/database
# 'cmd' is module parameter # 'cmd' is module parameter
- name: Run command if /path/to/database does not exist (with 'cmd' parameter) - name: Run command if /path/to/database does not exist (with 'cmd' parameter)
command: ansible.builtin.command:
cmd: /usr/bin/make_database.sh db_user db_name cmd: /usr/bin/make_database.sh db_user db_name
creates: /path/to/database creates: /path/to/database
- name: Change the working directory to somedir/ and run the command as db_owner if /path/to/database does not exist - name: Change the working directory to somedir/ and run the command as db_owner if /path/to/database does not exist
command: /usr/bin/make_database.sh db_user db_name ansible.builtin.command: /usr/bin/make_database.sh db_user db_name
become: yes become: yes
become_user: db_owner become_user: db_owner
args: args:
@ -132,7 +133,7 @@ EXAMPLES = r'''
# argv (list) arguments, each argument on a separate line, 'args' keyword not necessary # argv (list) arguments, each argument on a separate line, 'args' keyword not necessary
# 'argv' is a parameter, indented one level from the module # 'argv' is a parameter, indented one level from the module
- name: Use 'argv' to send a command as a list - leave 'command' empty - name: Use 'argv' to send a command as a list - leave 'command' empty
command: ansible.builtin.command:
argv: argv:
- /usr/bin/make_database.sh - /usr/bin/make_database.sh
- Username with whitespace - Username with whitespace
@ -140,7 +141,7 @@ EXAMPLES = r'''
creates: /path/to/database creates: /path/to/database
- name: Safely use templated variable to run command. Always use the quote filter to avoid injection issues - name: Safely use templated variable to run command. Always use the quote filter to avoid injection issues
command: cat {{ myfile|quote }} ansible.builtin.command: cat {{ myfile|quote }}
register: myoutput register: myoutput
''' '''
@ -151,49 +152,49 @@ msg:
type: bool type: bool
sample: True sample: True
start: start:
description: The command execution start time description: The command execution start time.
returned: always returned: always
type: str type: str
sample: '2017-09-29 22:03:48.083128' sample: '2017-09-29 22:03:48.083128'
end: end:
description: The command execution end time description: The command execution end time.
returned: always returned: always
type: str type: str
sample: '2017-09-29 22:03:48.084657' sample: '2017-09-29 22:03:48.084657'
delta: delta:
description: The command execution delta time description: The command execution delta time.
returned: always returned: always
type: str type: str
sample: '0:00:00.001529' sample: '0:00:00.001529'
stdout: stdout:
description: The command standard output description: The command standard output.
returned: always returned: always
type: str type: str
sample: 'Clustering node rabbit@slave1 with rabbit@master …' sample: 'Clustering node rabbit@slave1 with rabbit@master …'
stderr: stderr:
description: The command standard error description: The command standard error.
returned: always returned: always
type: str type: str
sample: 'ls cannot access foo: No such file or directory' sample: 'ls cannot access foo: No such file or directory'
cmd: cmd:
description: The command executed by the task description: The command executed by the task.
returned: always returned: always
type: list type: list
sample: sample:
- echo - echo
- hello - hello
rc: rc:
description: The command return code (0 means success) description: The command return code (0 means success).
returned: always returned: always
type: int type: int
sample: 0 sample: 0
stdout_lines: stdout_lines:
description: The command standard output split in lines description: The command standard output split in lines.
returned: always returned: always
type: list type: list
sample: [u'Clustering node rabbit@slave1 with rabbit@master …'] sample: [u'Clustering node rabbit@slave1 with rabbit@master …']
stderr_lines: stderr_lines:
description: The command standard error split in lines description: The command standard error split in lines.
returned: always returned: always
type: list type: list
sample: [u'ls cannot access foo: No such file or directory', u'ls …'] sample: [u'ls cannot access foo: No such file or directory', u'ls …']

2
lib/ansible/modules/debug.py
Unescape Escape View File

@ -34,7 +34,7 @@ options:
type: str type: str
verbosity: verbosity:
description: description:
- A number that controls when the debug is run, if you set to 3 it will only run debug when -vvv or above - A number that controls when the debug is run, if you set to 3 it will only run debug when -vvv or above.
type: int type: int
default: 0 default: 0
version_added: '2.1' version_added: '2.1'

10
lib/ansible/modules/expect.py
Unescape Escape View File

@ -12,7 +12,7 @@ DOCUMENTATION = r'''
--- ---
module: expect module: expect
version_added: '2.0' version_added: '2.0'
short_description: Executes a command and responds to prompts. short_description: Executes a command and responds to prompts
description: description:
- The C(expect) module executes a command and responds to prompts. - The C(expect) module executes a command and responds to prompts.
- The given command will be executed on all selected nodes. It will not be - The given command will be executed on all selected nodes. It will not be
@ -58,7 +58,7 @@ requirements:
- pexpect >= 3.3 - pexpect >= 3.3
notes: notes:
- If you want to run a command through the shell (say you are using C(<), - If you want to run a command through the shell (say you are using C(<),
C(>), C(|), etc), you must specify a shell in the command such as C(>), C(|), and so on), you must specify a shell in the command such as
C(/bin/bash -c "/path/to/something | grep else"). C(/bin/bash -c "/path/to/something | grep else").
- The question, or key, under I(responses) is a python regex match. Case - The question, or key, under I(responses) is a python regex match. Case
insensitive searches are indicated with a prefix of C(?i). insensitive searches are indicated with a prefix of C(?i).
@ -68,7 +68,7 @@ notes:
the response. The list functionality is new in 2.1. the response. The list functionality is new in 2.1.
- The M(ansible.builtin.expect) module is designed for simple scenarios. - The M(ansible.builtin.expect) module is designed for simple scenarios.
For more complex needs, consider the use of expect code with the M(ansible.builtin.shell) For more complex needs, consider the use of expect code with the M(ansible.builtin.shell)
or M(ansible.builtin.script) modules. (An example is part of the M(ansible.builtin.shell) module documentation) or M(ansible.builtin.script) modules. (An example is part of the M(ansible.builtin.shell) module documentation).
seealso: seealso:
- module: ansible.builtin.script - module: ansible.builtin.script
- module: ansible.builtin.shell - module: ansible.builtin.shell
@ -77,7 +77,7 @@ author: "Matt Martz (@sivel)"
EXAMPLES = r''' EXAMPLES = r'''
- name: Case insensitive password string match - name: Case insensitive password string match
expect: ansible.builtin.expect:
command: passwd username command: passwd username
responses: responses:
(?i)password: "MySekretPa$$word" (?i)password: "MySekretPa$$word"
@ -85,7 +85,7 @@ EXAMPLES = r'''
no_log: true no_log: true
- name: Generic question with multiple different responses - name: Generic question with multiple different responses
expect: ansible.builtin.expect:
command: /path/to/custom/command command: /path/to/custom/command
responses: responses:
Question: Question:

49
lib/ansible/modules/git.py
Unescape Escape View File

@ -33,12 +33,12 @@ options:
description: description:
- What version of the repository to check out. This can be - What version of the repository to check out. This can be
the literal string C(HEAD), a branch name, a tag name. the literal string C(HEAD), a branch name, a tag name.
It can also be a I(SHA-1) hash, in which case C(refspec) needs It can also be a I(SHA-1) hash, in which case I(refspec) needs
to be specified if the given revision is not already available. to be specified if the given revision is not already available.
default: "HEAD" default: "HEAD"
accept_hostkey: accept_hostkey:
description: description:
- if C(yes), ensure that "-o StrictHostKeyChecking=no" is - If C(yes), ensure that "-o StrictHostKeyChecking=no" is
present as an ssh option. present as an ssh option.
type: bool type: bool
default: 'no' default: 'no'
@ -57,7 +57,7 @@ options:
version_added: "1.5" version_added: "1.5"
reference: reference:
description: description:
- Reference repository (see "git clone --reference ...") - Reference repository (see "git clone --reference ...").
version_added: "1.4" version_added: "1.4"
remote: remote:
description: description:
@ -77,7 +77,7 @@ options:
- If C(yes), any modified files in the working - If C(yes), any modified files in the working
repository will be discarded. Prior to 0.7, this was always repository will be discarded. Prior to 0.7, this was always
'yes' and could not be disabled. Prior to 1.9, the default was 'yes' and could not be disabled. Prior to 1.9, the default was
`yes` `yes`.
type: bool type: bool
default: 'no' default: 'no'
version_added: "0.7" version_added: "0.7"
@ -89,13 +89,13 @@ options:
version_added: "1.2" version_added: "1.2"
clone: clone:
description: description:
- If C(no), do not clone the repository even if it does not exist locally - If C(no), do not clone the repository even if it does not exist locally.
type: bool type: bool
default: 'yes' default: 'yes'
version_added: "1.9" version_added: "1.9"
update: update:
description: description:
- If C(no), do not retrieve new revisions from the origin repository - If C(no), do not retrieve new revisions from the origin repository.
- Operations like archive will work on the existing (old) repository and might - Operations like archive will work on the existing (old) repository and might
not respond to changes to the options version or remote. not respond to changes to the options version or remote.
type: bool type: bool
@ -108,7 +108,7 @@ options:
version_added: "1.4" version_added: "1.4"
bare: bare:
description: description:
- if C(yes), repository will be created as a bare repo, otherwise - If C(yes), repository will be created as a bare repo, otherwise
it will be a standard repo with a workspace. it will be a standard repo with a workspace.
type: bool type: bool
default: 'no' default: 'no'
@ -121,7 +121,7 @@ options:
recursive: recursive:
description: description:
- if C(no), repository will be cloned without the --recursive - If C(no), repository will be cloned without the --recursive
option, skipping sub-modules. option, skipping sub-modules.
type: bool type: bool
default: 'yes' default: 'yes'
@ -129,7 +129,7 @@ options:
track_submodules: track_submodules:
description: description:
- if C(yes), submodules will track the latest commit on their - If C(yes), submodules will track the latest commit on their
master branch (or other branch specified in .gitmodules). If master branch (or other branch specified in .gitmodules). If
C(no), submodules will be kept at the revision specified by the C(no), submodules will be kept at the revision specified by the
main project. This is equivalent to specifying the --remote flag main project. This is equivalent to specifying the --remote flag
@ -140,8 +140,8 @@ options:
verify_commit: verify_commit:
description: description:
- if C(yes), when cloning or checking out a C(version) verify the - If C(yes), when cloning or checking out a I(version) verify the
signature of a GPG signed commit. This requires C(git) version>=2.1.0 signature of a GPG signed commit. This requires git version>=2.1.0
to be installed. The commit MUST be signed and the public key MUST to be installed. The commit MUST be signed and the public key MUST
be present in the GPG keyring. be present in the GPG keyring.
type: bool type: bool
@ -153,14 +153,14 @@ options:
- Specify archive file path with extension. If specified, creates an - Specify archive file path with extension. If specified, creates an
archive file of the specified format containing the tree structure archive file of the specified format containing the tree structure
for the source tree. for the source tree.
Allowed archive formats ["zip", "tar.gz", "tar", "tgz"] Allowed archive formats ["zip", "tar.gz", "tar", "tgz"].
- This will clone and perform git archive from local directory as not - This will clone and perform git archive from local directory as not
all git servers support git archive. all git servers support git archive.
version_added: "2.4" version_added: "2.4"
archive_prefix: archive_prefix:
description: description:
- Specify a prefix to add to each file path in archive. Requires C(archive) to be specified. - Specify a prefix to add to each file path in archive. Requires I(archive) to be specified.
version_added: "2.10" version_added: "2.10"
type: str type: str
@ -188,47 +188,48 @@ notes:
one solution is to use the option accept_hostkey. Another solution is to one solution is to use the option accept_hostkey. Another solution is to
add the remote host public key in C(/etc/ssh/ssh_known_hosts) before calling add the remote host public key in C(/etc/ssh/ssh_known_hosts) before calling
the git module, with the following command: ssh-keyscan -H remote_host.com >> /etc/ssh/ssh_known_hosts." the git module, with the following command: ssh-keyscan -H remote_host.com >> /etc/ssh/ssh_known_hosts."
- Supports C(check_mode).
''' '''
EXAMPLES = ''' EXAMPLES = '''
- name: Git checkout - name: Git checkout
git: ansible.builtin.git:
repo: 'https://foosball.example.org/path/to/repo.git' repo: 'https://foosball.example.org/path/to/repo.git'
dest: /srv/checkout dest: /srv/checkout
version: release-0.22 version: release-0.22
- name: Read-write git checkout from github - name: Read-write git checkout from github
git: ansible.builtin.git:
repo: git@github.com:mylogin/hello.git repo: git@github.com:mylogin/hello.git
dest: /home/mylogin/hello dest: /home/mylogin/hello
- name: Just ensuring the repo checkout exists - name: Just ensuring the repo checkout exists
git: ansible.builtin.git:
repo: 'https://foosball.example.org/path/to/repo.git' repo: 'https://foosball.example.org/path/to/repo.git'
dest: /srv/checkout dest: /srv/checkout
update: no update: no
- name: Just get information about the repository whether or not it has already been cloned locally - name: Just get information about the repository whether or not it has already been cloned locally
git: ansible.builtin.git:
repo: 'https://foosball.example.org/path/to/repo.git' repo: 'https://foosball.example.org/path/to/repo.git'
dest: /srv/checkout dest: /srv/checkout
clone: no clone: no
update: no update: no
- name: Checkout a github repo and use refspec to fetch all pull requests - name: Checkout a github repo and use refspec to fetch all pull requests
git: ansible.builtin.git:
repo: https://github.com/ansible/ansible-examples.git repo: https://github.com/ansible/ansible-examples.git
dest: /src/ansible-examples dest: /src/ansible-examples
refspec: '+refs/pull/*:refs/heads/*' refspec: '+refs/pull/*:refs/heads/*'
- name: Create git archive from repo - name: Create git archive from repo
git: ansible.builtin.git:
repo: https://github.com/ansible/ansible-examples.git repo: https://github.com/ansible/ansible-examples.git
dest: /src/ansible-examples dest: /src/ansible-examples
archive: /tmp/ansible-examples.zip archive: /tmp/ansible-examples.zip
- name: Clone a repo with separate git directory - name: Clone a repo with separate git directory
git: ansible.builtin.git:
repo: https://github.com/ansible/ansible-examples.git repo: https://github.com/ansible/ansible-examples.git
dest: /src/ansible-examples dest: /src/ansible-examples
separate_git_dir: /src/ansible-examples.git separate_git_dir: /src/ansible-examples.git
@ -236,12 +237,12 @@ EXAMPLES = '''
RETURN = ''' RETURN = '''
after: after:
description: last commit revision of the repository retrieved during the update description: Last commit revision of the repository retrieved during the update.
returned: success returned: success
type: str type: str
sample: 4c020102a9cd6fe908c9a4a326a38f972f63a903 sample: 4c020102a9cd6fe908c9a4a326a38f972f63a903
before: before:
description: commit revision before the repository was updated, "null" for new repository description: Commit revision before the repository was updated, "null" for new repository.
returned: success returned: success
type: str type: str
sample: 67c04ebe40a003bda0efb34eacfb93b0cafdf628 sample: 67c04ebe40a003bda0efb34eacfb93b0cafdf628
@ -256,12 +257,12 @@ warnings:
type: str type: str
sample: Your git version is too old to fully support the depth argument. Falling back to full checkouts. sample: Your git version is too old to fully support the depth argument. Falling back to full checkouts.
git_dir_now: git_dir_now:
description: Contains the new path of .git directory if it's changed description: Contains the new path of .git directory if it is changed.
returned: success returned: success
type: str type: str
sample: /path/to/new/git/dir sample: /path/to/new/git/dir
git_dir_before: git_dir_before:
description: Contains the original path of .git directory if it's changed description: Contains the original path of .git directory if it is changed.
returned: success returned: success
type: str type: str
sample: /path/to/old/git/dir sample: /path/to/old/git/dir

2
lib/ansible/modules/group.py
Unescape Escape View File

@ -45,7 +45,7 @@ options:
description: description:
- Forces the use of "local" command alternatives on platforms that implement it. - Forces the use of "local" command alternatives on platforms that implement it.
- This is useful in environments that use centralized authentication when you want to manipulate the local groups. - This is useful in environments that use centralized authentication when you want to manipulate the local groups.
(e.g. it uses C(lgroupadd) instead of C(groupadd)). (for example, it uses C(lgroupadd) instead of C(groupadd)).
- This requires that these commands exist on the targeted host, otherwise it will be a fatal error. - This requires that these commands exist on the targeted host, otherwise it will be a fatal error.
type: bool type: bool
default: no default: no

10
lib/ansible/modules/group_by.py
Unescape Escape View File

@ -39,20 +39,20 @@ author:
EXAMPLES = r''' EXAMPLES = r'''
- name: Create groups based on the machine architecture - name: Create groups based on the machine architecture
group_by: ansible.builtin.group_by:
key: machine_{{ ansible_machine }} key: machine_{{ ansible_machine }}
- name: Create groups like 'virt_kvm_host' - name: Create groups like 'virt_kvm_host'
group_by: ansible.builtin.group_by:
key: virt_{{ ansible_virtualization_type }}_{{ ansible_virtualization_role }} key: virt_{{ ansible_virtualization_type }}_{{ ansible_virtualization_role }}
- name: Create nested groups - name: Create nested groups
group_by: ansible.builtin.group_by:
key: el{{ ansible_distribution_major_version }}-{{ ansible_architecture }} key: el{{ ansible_distribution_major_version }}-{{ ansible_architecture }}
parents: parents:
- el{{ ansible_distribution_major_version }} - el{{ ansible_distribution_major_version }}
# Add all active hosts to a static group - name: Add all active hosts to a static group
- group_by: ansible.builtin.group_by:
key: done key: done
''' '''

2
lib/ansible/modules/hostname.py
Unescape Escape View File

@ -36,7 +36,7 @@ options:
EXAMPLES = ''' EXAMPLES = '''
- name: Set a hostname - name: Set a hostname
hostname: ansible.builtin.hostname:
name: web01 name: web01
''' '''

9
lib/ansible/modules/package.py
Unescape Escape View File

@ -33,9 +33,8 @@ options:
required: true required: true
use: use:
description: description:
- The required package manager module to use (yum, apt, etc). The default 'auto' will use existing facts or try to autodetect it. - The required package manager module to use (`yum`, `apt`, and so on). The default 'auto' will use existing facts or try to autodetect it.
- You should only use this field if the automatic selection is not working for some reason. - You should only use this field if the automatic selection is not working for some reason.
required: false
default: auto default: auto
requirements: requirements:
- Whatever is required for the package plugins specific for each system. - Whatever is required for the package plugins specific for each system.
@ -45,18 +44,18 @@ notes:
''' '''
EXAMPLES = ''' EXAMPLES = '''
- name: Install ntpdate - name: Install ntpdate
package: ansible.builtin.package:
name: ntpdate name: ntpdate
state: present state: present
# This uses a variable as this changes per distribution. # This uses a variable as this changes per distribution.
- name: Remove the apache package - name: Remove the apache package
package: ansible.builtin.package:
name: "{{ apache }}" name: "{{ apache }}"
state: absent state: absent
- name: Install the latest version of Apache and MariaDB - name: Install the latest version of Apache and MariaDB
package: ansible.builtin.package:
name: name:
- httpd - httpd
- mariadb-server - mariadb-server

14
lib/ansible/modules/package_facts.py
Unescape Escape View File

@ -10,9 +10,9 @@ __metaclass__ = type
DOCUMENTATION = ''' DOCUMENTATION = '''
module: package_facts module: package_facts
short_description: package information as facts short_description: Package information as facts
description: description:
- Return information about installed packages as facts - Return information about installed packages as facts.
options: options:
manager: manager:
description: description:
@ -39,19 +39,21 @@ author:
- Matthew Jones (@matburt) - Matthew Jones (@matburt)
- Brian Coca (@bcoca) - Brian Coca (@bcoca)
- Adam Miller (@maxamillion) - Adam Miller (@maxamillion)
notes:
- Supports C(check_mode).
''' '''
EXAMPLES = ''' EXAMPLES = '''
- name: Gather the package facts - name: Gather the package facts
package_facts: ansible.builtin.package_facts:
manager: auto manager: auto
- name: Print the package facts - name: Print the package facts
debug: ansible.builtin.debug:
var: ansible_facts.packages var: ansible_facts.packages
- name: Check whether a package called foobar is installed - name: Check whether a package called foobar is installed
debug: ansible.builtin.debug:
msg: "{{ ansible_facts.packages['foobar'] | length }} versions of foobar are installed!" msg: "{{ ansible_facts.packages['foobar'] | length }} versions of foobar are installed!"
when: "'foobar' in ansible_facts.packages" when: "'foobar' in ansible_facts.packages"
@ -59,7 +61,7 @@ EXAMPLES = '''
RETURN = ''' RETURN = '''
ansible_facts: ansible_facts:
description: facts to add to ansible_facts description: Facts to add to ansible_facts.
returned: always returned: always
type: complex type: complex
contains: contains:

77
lib/ansible/modules/user.py
Unescape Escape View File

@ -203,7 +203,7 @@ options:
description: description:
- Forces the use of "local" command alternatives on platforms that implement it. - Forces the use of "local" command alternatives on platforms that implement it.
- This is useful in environments that use centralized authentication when you want to manipulate the local users - This is useful in environments that use centralized authentication when you want to manipulate the local users
(i.e. it uses C(luseradd) instead of C(useradd)). (in other words, it uses C(luseradd) instead of C(useradd)).
- This will check C(/etc/passwd) for an existing account before invoking commands. If the local account database - This will check C(/etc/passwd) for an existing account before invoking commands. If the local account database
exists somewhere other than C(/etc/passwd), this setting will not work properly. exists somewhere other than C(/etc/passwd), this setting will not work properly.
- This requires that the above commands as well as C(/etc/passwd) must exist on the target host, otherwise it will be a fatal error. - This requires that the above commands as well as C(/etc/passwd) must exist on the target host, otherwise it will be a fatal error.
@ -250,6 +250,7 @@ notes:
C(pw userdel) remove, C(pw lock) to lock, and C(pw unlock) to unlock accounts. C(pw userdel) remove, C(pw lock) to lock, and C(pw unlock) to unlock accounts.
- On all other platforms, this module uses C(useradd) to create, C(usermod) to modify, and - On all other platforms, this module uses C(useradd) to create, C(usermod) to modify, and
C(userdel) to remove accounts. C(userdel) to remove accounts.
- Supports C(check_mode).
seealso: seealso:
- module: ansible.posix.authorized_key - module: ansible.posix.authorized_key
- module: ansible.builtin.group - module: ansible.builtin.group
@ -260,64 +261,64 @@ author:
EXAMPLES = r''' EXAMPLES = r'''
- name: Add the user 'johnd' with a specific uid and a primary group of 'admin' - name: Add the user 'johnd' with a specific uid and a primary group of 'admin'
user: ansible.builtin.user:
name: johnd name: johnd
comment: John Doe comment: John Doe
uid: 1040 uid: 1040
group: admin group: admin
- name: Add the user 'james' with a bash shell, appending the group 'admins' and 'developers' to the user's groups - name: Add the user 'james' with a bash shell, appending the group 'admins' and 'developers' to the user's groups
user: ansible.builtin.user:
name: james name: james
shell: /bin/bash shell: /bin/bash
groups: admins,developers groups: admins,developers
append: yes append: yes
- name: Remove the user 'johnd' - name: Remove the user 'johnd'
user: ansible.builtin.user:
name: johnd name: johnd
state: absent state: absent
remove: yes remove: yes
- name: Create a 2048-bit SSH key for user jsmith in ~jsmith/.ssh/id_rsa - name: Create a 2048-bit SSH key for user jsmith in ~jsmith/.ssh/id_rsa
user: ansible.builtin.user:
name: jsmith name: jsmith
generate_ssh_key: yes generate_ssh_key: yes
ssh_key_bits: 2048 ssh_key_bits: 2048
ssh_key_file: .ssh/id_rsa ssh_key_file: .ssh/id_rsa
- name: Added a consultant whose account you want to expire - name: Added a consultant whose account you want to expire
user: ansible.builtin.user:
name: james18 name: james18
shell: /bin/zsh shell: /bin/zsh
groups: developers groups: developers
expires: 1422403387 expires: 1422403387
- name: Starting at Ansible 2.6, modify user, remove expiry time - name: Starting at Ansible 2.6, modify user, remove expiry time
user: ansible.builtin.user:
name: james18 name: james18
expires: -1 expires: -1
''' '''
RETURN = r''' RETURN = r'''
append: append:
description: Whether or not to append the user to groups description: Whether or not to append the user to groups.
returned: When state is 'present' and the user exists returned: When state is C(present) and the user exists
type: bool type: bool
sample: True sample: True
comment: comment:
description: Comment section from passwd file, usually the user name description: Comment section from passwd file, usually the user name.
returned: When user exists returned: When user exists
type: str type: str
sample: Agent Smith sample: Agent Smith
create_home: create_home:
description: Whether or not to create the home directory description: Whether or not to create the home directory.
returned: When user does not exist and not check mode returned: When user does not exist and not check mode
type: bool type: bool
sample: True sample: True
force: force:
description: Whether or not a user account was forcibly deleted description: Whether or not a user account was forcibly deleted.
returned: When state is 'absent' and user exists returned: When I(state) is C(absent) and user exists
type: bool type: bool
sample: False sample: False
group: group:
@ -326,76 +327,76 @@ group:
type: int type: int
sample: 1001 sample: 1001
groups: groups:
description: List of groups of which the user is a member description: List of groups of which the user is a member.
returned: When C(groups) is not empty and C(state) is 'present' returned: When I(groups) is not empty and I(state) is C(present)
type: str type: str
sample: 'chrony,apache' sample: 'chrony,apache'
home: home:
description: "Path to user's home directory" description: "Path to user's home directory."
returned: When C(state) is 'present' returned: When I(state) is C(present)
type: str type: str
sample: '/home/asmith' sample: '/home/asmith'
move_home: move_home:
description: Whether or not to move an existing home directory description: Whether or not to move an existing home directory.
returned: When C(state) is 'present' and user exists returned: When I(state) is C(present) and user exists
type: bool type: bool
sample: False sample: False
name: name:
description: User account name description: User account name.
returned: always returned: always
type: str type: str
sample: asmith sample: asmith
password: password:
description: Masked value of the password description: Masked value of the password.
returned: When C(state) is 'present' and C(password) is not empty returned: When I(state) is C(present) and I(password) is not empty
type: str type: str
sample: 'NOT_LOGGING_PASSWORD' sample: 'NOT_LOGGING_PASSWORD'
remove: remove:
description: Whether or not to remove the user account description: Whether or not to remove the user account.
returned: When C(state) is 'absent' and user exists returned: When I(state) is C(absent) and user exists
type: bool type: bool
sample: True sample: True
shell: shell:
description: User login shell description: User login shell.
returned: When C(state) is 'present' returned: When I(state) is C(present)
type: str type: str
sample: '/bin/bash' sample: '/bin/bash'
ssh_fingerprint: ssh_fingerprint:
description: Fingerprint of generated SSH key description: Fingerprint of generated SSH key.
returned: When C(generate_ssh_key) is C(True) returned: When I(generate_ssh_key) is C(True)
type: str type: str
sample: '2048 SHA256:aYNHYcyVm87Igh0IMEDMbvW0QDlRQfE0aJugp684ko8 ansible-generated on host (RSA)' sample: '2048 SHA256:aYNHYcyVm87Igh0IMEDMbvW0QDlRQfE0aJugp684ko8 ansible-generated on host (RSA)'
ssh_key_file: ssh_key_file:
description: Path to generated SSH private key file description: Path to generated SSH private key file.
returned: When C(generate_ssh_key) is C(True) returned: When I(generate_ssh_key) is C(True)
type: str type: str
sample: /home/asmith/.ssh/id_rsa sample: /home/asmith/.ssh/id_rsa
ssh_public_key: ssh_public_key:
description: Generated SSH public key file description: Generated SSH public key file.
returned: When C(generate_ssh_key) is C(True) returned: When I(generate_ssh_key) is C(True)
type: str type: str
sample: > sample: >
'ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC95opt4SPEC06tOYsJQJIuN23BbLMGmYo8ysVZQc4h2DZE9ugbjWWGS1/pweUGjVstgzMkBEeBCByaEf/RJKNecKRPeGd2Bw9DCj/bn5Z6rGfNENKBmo 'ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC95opt4SPEC06tOYsJQJIuN23BbLMGmYo8ysVZQc4h2DZE9ugbjWWGS1/pweUGjVstgzMkBEeBCByaEf/RJKNecKRPeGd2Bw9DCj/bn5Z6rGfNENKBmo
618mUJBvdlEgea96QGjOwSB7/gmonduC7gsWDMNcOdSE3wJMTim4lddiBx4RgC9yXsJ6Tkz9BHD73MXPpT5ETnse+A3fw3IGVSjaueVnlUyUmOBf7fzmZbhlFVXf2Zi2rFTXqvbdGHKkzpw1U8eB8xFPP7y 618mUJBvdlEgea96QGjOwSB7/gmonduC7gsWDMNcOdSE3wJMTim4lddiBx4RgC9yXsJ6Tkz9BHD73MXPpT5ETnse+A3fw3IGVSjaueVnlUyUmOBf7fzmZbhlFVXf2Zi2rFTXqvbdGHKkzpw1U8eB8xFPP7y
d5u1u0e6Acju/8aZ/l17IDFiLke5IzlqIMRTEbDwLNeO84YQKWTm9fODHzhYe0yvxqLiK07 ansible-generated on host' d5u1u0e6Acju/8aZ/l17IDFiLke5IzlqIMRTEbDwLNeO84YQKWTm9fODHzhYe0yvxqLiK07 ansible-generated on host'
stderr: stderr:
description: Standard error from running commands description: Standard error from running commands.
returned: When stderr is returned by a command that is run returned: When stderr is returned by a command that is run
type: str type: str
sample: Group wheels does not exist sample: Group wheels does not exist
stdout: stdout:
description: Standard output from running commands description: Standard output from running commands.
returned: When standard output is returned by the command that is run returned: When standard output is returned by the command that is run
type: str type: str
sample: sample:
system: system:
description: Whether or not the account is a system account description: Whether or not the account is a system account.
returned: When C(system) is passed to the module and the account does not exist returned: When I(system) is passed to the module and the account does not exist
type: bool type: bool
sample: True sample: True
uid: uid:
description: User ID of the user account description: User ID of the user account.
returned: When C(UID) is passed to the module returned: When I(uid) is passed to the module
type: int type: int
sample: 1044 sample: 1044
''' '''

Write Preview
Loading…
Cancel
Save