Jumbo DOCUMENTATION patch

reviewable/pr18780/r1
Jan-Piet Mens 12 years ago
parent d7ee918419
commit c78a0a4a49

2
apt

@ -34,7 +34,7 @@ options:
default: null default: null
state: state:
description: description:
- Indicate the package state - Indicate the desired package state
required: false required: false
default: present default: present
choices: [ "installed", "latest", "remove", "absent", "present" ] choices: [ "installed", "latest", "remove", "absent", "present" ]

@ -44,7 +44,7 @@ options:
choices: [ "present", "absent" ] choices: [ "present", "absent" ]
notes: notes:
- This module requires C(apt-add-repository) be available on destination server. To ensure this package is available use the C(apt) module and install the C(python-software-properties) package before using this module. - This module requires C(apt-add-repository) be available on destination server. To ensure this package is available use the C(apt) module and install the C(python-software-properties) package before using this module.
- This module works on Ubuntu and unstable Debian only, see *(https://github.com/ansible/ansible/pull/1082). - This module works on Ubuntu and unstable Debian only, see U(https://github.com/ansible/ansible/pull/1082).
- A bug in C(apt-add-repository) always adds C(deb) and C(deb-src) types for repositories (see the issue on Launchpad U(https://bugs.launchpad.net/ubuntu/+source/software-properties/+bug/987264)), if some repo don't have source (eg MongoDB repo from 10gen) the system fails while updating repositories. - A bug in C(apt-add-repository) always adds C(deb) and C(deb-src) types for repositories (see the issue on Launchpad U(https://bugs.launchpad.net/ubuntu/+source/software-properties/+bug/987264)), if some repo don't have source (eg MongoDB repo from 10gen) the system fails while updating repositories.
author: Matt Wright author: Matt Wright
examples: examples:

@ -24,9 +24,9 @@ along with Ansible. If not, see <http://www.gnu.org/licenses/>.
DOCUMENTATION = ''' DOCUMENTATION = '''
--- ---
module: authorized_key module: authorized_key
short_description: Adds or removes an authorized key for a user from a remote host. short_description: Adds or removes an SSH authorized key
description: description:
- Adds or removes an authorized key for a user from a remote host. - Adds or removes an SSH authorized key for a user from a remote host.
version_added: "0.5" version_added: "0.5"
options: options:
user: user:

@ -31,7 +31,7 @@ DOCUMENTATION = '''
module: command module: command
short_description: Executes a command on a remote node short_description: Executes a command on a remote node
description: description:
- The command module takes the command name followed by a list of arguments, space delimited. - The command module takes the command name followed by a list of space-delimited arguments.
- 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
processed through the shell, so variables like C($HOME) and operations processed through the shell, so variables like C($HOME) and operations
like C("<"), C(">"), C("|"), and C("&") will not work. As such, all like C("<"), C(">"), C("|"), and C("&") will not work. As such, all

@ -43,9 +43,9 @@ examples:
- code: easy_install name=pip - code: easy_install name=pip
description: "Examples from Ansible Playbooks" description: "Examples from Ansible Playbooks"
- code: easy_install name=flask virtualenv=/webapps/myapp/venv - code: easy_install name=flask virtualenv=/webapps/myapp/venv
description: "Install I(flask) into the specified I(virtualenv)" description: "Install I(Flask) (U(http://flask.pocoo.org/)) into the specified I(virtualenv)"
notes: notes:
- Please note that the M(easy_install) command can only install Python - Please note that the M(easy_install) module can only install Python
libraries. Thus this module is not able to remove libraries. It is libraries. Thus this module is not able to remove libraries. It is
generally recommended to use the M(pip) module which you can first install generally recommended to use the M(pip) module which you can first install
using M(easy_install). using M(easy_install).

@ -25,8 +25,9 @@ DOCUMENTATION = '''
module: facter module: facter
short_description: Runs the discovery program I(facter) on the remote system short_description: Runs the discovery program I(facter) on the remote system
description: description:
- Runs the discovery program I(facter) on the remote system, returning JSON - Runs the I(facter) discovery program
data that can be useful for inventory purposes. (U(https://github.com/puppetlabs/facter)) on the remote system, returning
JSON data that can be useful for inventory purposes.
version_added: "0.2" version_added: "0.2"
options: [] options: []
examples: examples:

67
file

@ -46,19 +46,82 @@ options:
aliases: [] aliases: []
state: state:
description: description:
- If directory, all immediate subdirectories will be created if they do not exist. If I(file), the file will NOT be created if it does not exist, see the M(copy) or M(template) module if you want that behavior. If I(link), the symbolic link will be created or changed. If absent, directories will be recursively deleted, and files or symlinks will be unlinked. - If C(directory), all immediate subdirectories will be created if they
do not exist. If C(file), the file will NOT be created if it does not
exist, see the M(copy) or M(template) module if you want that behavior.
If C(link), the symbolic link will be created or changed. If C(absent),
directories will be recursively deleted, and files or symlinks will be
unlinked.
required: false required: false
default: file default: file
choices: [ file, link, directory, absent ] choices: [ file, link, directory, absent ]
mode: mode:
required: false
default: null
choices: []
description:
- mode the file or directory should be, such as 0644 as would be fed to
owner:
required: false
default: null
choices: []
description:
- name of the user that should own the file/directory, as would be fed to I(chown)
group:
required: false
default: null
choices: []
description:
- name of the group that should own the file/directory, as would be fed to I(chown)
src:
required: false
default: null
choices: []
description:
- path of the file to link to (applies only to C(state=link)).
seuser:
required: false
default: null
choices: []
description:
- user part of SELinux file context. Will default to system policy, if
applicable. If set to C(_default), it will use the C(user) portion of the
the policy if available
serole:
required: false
default: null
choices: []
description:
- role part of SELinux file context, C(_default) feature works as for I(seuser).
setype:
required: false
default: null
choices: []
description:
- type part of SELinux file context, C(_default) feature works as for I(seuser).
selevel:
required: false
default: "s0"
choices: []
description:
- level part of the SELinux file context. This is the MLS/MCS attribute,
sometimes known as the C(range). C(_default) feature works as for
I(seuser).
context:
required: false
default: null
choices: [ "default" ]
description: description:
- mode the file or directory should be, such as 0644 as would be fed to I(chmod). English modes like B(g+x) are not yet supported - accepts only C(default) as value. This will restore a file's SELinux context
in the policy. Does nothing if no default value is available.
examples: examples:
- code: file path=/etc/foo.conf owner=foo group=foo mode=0644 - code: file path=/etc/foo.conf owner=foo group=foo mode=0644
description: Example from Ansible Playbooks description: Example from Ansible Playbooks
- code: file src=/file/to/link/to dest=/path/to/symlink owner=foo group=foo state=link
notes: notes:
- See also M(copy), M(template), M(assemble) - See also M(copy), M(template), M(assemble)
requirements: [ ] requirements: [ ]
author: Michael DeHaan
''' '''
def add_path_info(kwargs): def add_path_info(kwargs):

@ -38,8 +38,8 @@ options:
regexp: regexp:
required: true required: true
description: description:
- The regular expression to look for in the file. For I(state=present), - The regular expression to look for in the file. For C(state=present),
the pattern to replace. For I(state=absent), the pattern of the line the pattern to replace. For C(state=absent), the pattern of the line
to remove. to remove.
state: state:
required: false required: false
@ -51,13 +51,13 @@ options:
line: line:
required: false required: false
description: description:
- Required for I(state=present). The line to insert/replace into the - Required for C(state=present). The line to insert/replace into the
file. Must match the value given to C(regexp). file. Must match the value given to C(regexp).
insertafter: insertafter:
required: false required: false
default: EOF default: EOF
description: description:
- Used with I(state=present). If specified, the line will be inserted - Used with C(state=present). If specified, the line will be inserted
after the specified regular expression. Two special values are after the specified regular expression. Two special values are
available; C(BOF) for inserting the line at the beginning of the available; C(BOF) for inserting the line at the beginning of the
file, and C(EOF) for inserting the line at the end of the file. file, and C(EOF) for inserting the line at the end of the file.

@ -65,10 +65,14 @@ options:
default: null default: null
examples: examples:
- code: mysql_db db=bobdata state=present - code: mysql_db db=bobdata state=present
description: create a new database with name 'bobdata' description: Create a new database with name 'bobdata'
notes: notes:
- Requires the MySQLdb Python package on the remote host. For Ubuntu, this is as easy as apt-get install python-mysqldb. - Requires the MySQLdb Python package on the remote host. For Ubuntu, this
- Both 'login_password' and 'login_username' are required when you are passing credentials. If none are present, the module will attempt to read the credentials from ~/.my.cnf, and finally fall back to using the MySQL default login of 'root' with no password. is as easy as apt-get install python-mysqldb.
- Both C(login_password) and C(login_username) are required when you are
passing credentials. If none are present, the module will attempt to read
the credentials from C(~/.my.cnf), and finally fall back to using the MySQL
default login of 'root' with no password.
requirements: [ ConfigParser ] requirements: [ ConfigParser ]
author: Mark Theunissen author: Mark Theunissen
''' '''

@ -75,9 +75,13 @@ examples:
- code: mydb.*:INSERT,UPDATE/anotherdb.*:SELECT/yetanotherdb.*:ALL - code: mydb.*:INSERT,UPDATE/anotherdb.*:SELECT/yetanotherdb.*:ALL
description: Example privileges string format description: Example privileges string format
notes: notes:
- Requires the MySQLdb Python package on the remote host. For Ubuntu, this is as easy as apt-get install python-mysqldb. - Requires the MySQLdb Python package on the remote host. For Ubuntu, this
- Both 'login_password' and 'login_username' are required when you are passing credentials. If none are present, the module will attempt to read the credentials from ~/.my.cnf, and finally fall back to using the MySQL default login of 'root' with no password. is as easy as apt-get install python-mysqldb.
requirements: [ ConfigParser ] - Both C(login_password) and C(login_username) are required when you are
passing credentials. If none are present, the module will attempt to read
the credentials from C(~/.my.cnf), and finally fall back to using the MySQL
default login of 'root' with no password.
requirements: [ "ConfigParser", "MySQLdb" ]
author: Mark Theunissen author: Mark Theunissen
''' '''

@ -24,7 +24,9 @@ DOCUMENTATION = '''
module: ohai module: ohai
short_description: Returns inventory data from I(ohai) short_description: Returns inventory data from I(ohai)
description: description:
- Similar to the M(facter) module, this returns JSON inventory data. - Similar to the M(facter) module, this runs the I(ohai) discovery program
(U(http://wiki.opscode.com/display/chef/Ohai)) on the remote host and
returns JSON inventory data.
I(Ohai) data is a bit more verbose and nested than I(facter). I(Ohai) data is a bit more verbose and nested than I(facter).
version_added: "0.6" version_added: "0.6"
options: [] options: []

@ -24,8 +24,10 @@ DOCUMENTATION = '''
module: ping module: ping
short_description: Try to connect to host and return pong on success. short_description: Try to connect to host and return pong on success.
description: description:
- A trivial test module, this module always returns 'pong' on successful contact. It does not make sense in playbooks, but is useful from /usr/bin/ansible - A trivial test module, this module always returns 'pong' on successful
version_added: "0.7" contact. It does not make sense in playbooks, but is useful from
C(/usr/bin/ansible)
version_added: "0.1"
examples: examples:
- code: ansible webservers -m ping - code: ansible webservers -m ping
description: Test 'webservers' status description: Test 'webservers' status

4
pip

@ -59,14 +59,14 @@ examples:
- code: pip name=flask version=0.8 - code: pip name=flask version=0.8
description: Install I(flask) python package on version 0.8. description: Install I(flask) python package on version 0.8.
- code: pip name=flask virtualenv=/srv/webapps/my_app/venv - code: pip name=flask virtualenv=/srv/webapps/my_app/venv
description: Install I(flask) python package in specified virtualenv. description: "Install I(Flask) (U(http://flask.pocoo.org/)) into the specified I(virtualenv)"
- code: pip requirements=/srv/webapps/my_app/src/requirements.txt - code: pip requirements=/srv/webapps/my_app/src/requirements.txt
description: Install specified python requirements. description: Install specified python requirements.
- code: pip requirements=/srv/webapps/my_app/src/requirements.txt virtualenv=/srv/webapps/my_app/venv - code: pip requirements=/srv/webapps/my_app/src/requirements.txt virtualenv=/srv/webapps/my_app/venv
description: Install specified python requirements in indicated virtualenv. description: Install specified python requirements in indicated virtualenv.
notes: notes:
- Please note that U(http://www.virtualenv.org/, virtualenv) must be installed on the remote host if the virtualenv parameter is specified. - Please note that U(http://www.virtualenv.org/, virtualenv) must be installed on the remote host if the virtualenv parameter is specified.
requirements: [ ] requirements: [ "virtualenv", "pip" ]
author: Matt Wright author: Matt Wright
''' '''

@ -36,7 +36,7 @@ options:
default: null default: null
login_password: login_password:
description: description:
- The passwordused to authenticate with - The password used to authenticate with
required: false required: false
default: null default: null
login_host: login_host:
@ -57,7 +57,7 @@ options:
choices: [ "present", "absent" ] choices: [ "present", "absent" ]
examples: examples:
- code: postgresql_db db=acme - code: postgresql_db db=acme
description: create a new database with name 'acme' description: Create a new database with name 'acme'
notes: notes:
- The default authentication assumes that you are either logging in as or sudo'ing to the postgres account on the host. - The default authentication assumes that you are either logging in as or sudo'ing to the postgres account on the host.
- This module uses psycopg2, a Python PostgreSQL database adapter. You must ensure that psycopg2 is installed on the host before using this module. If the remote host is the PostgreSQL server (which is the default case), then PostgreSQL must also be installed on the remote host. For Ubuntu-based systems, install the postgresql, libpq-dev, and python-psycopg2 packages on the remote host before using this module. - This module uses psycopg2, a Python PostgreSQL database adapter. You must ensure that psycopg2 is installed on the host before using this module. If the remote host is the PostgreSQL server (which is the default case), then PostgreSQL must also be installed on the remote host. For Ubuntu-based systems, install the postgresql, libpq-dev, and python-psycopg2 packages on the remote host before using this module.

@ -22,34 +22,36 @@ DOCUMENTATION = '''
--- ---
module: service module: service
author: Michael DeHaan author: Michael DeHaan
version_added: 0.0.1 version_added: 0.1
short_description: Manage services. short_description: Manage services.
description: description:
- Controls services on remote hosts. - Controls services on remote hosts.
options: options:
name: name:
required: true required: true
description: Name of the service. description:
- Name of the service.
state: state:
required: false required: false
choices: [ running, started, stopped, restarted, reloaded ] choices: [ running, started, stopped, restarted, reloaded ]
description: I(started), I(stopped), I(reloaded), I(restarted). description:
I(Started)/I(stopped) are idempotent actions that will - I(started), I(stopped), I(reloaded), I(restarted).
not run commands unless necessary. I(restarted) will I(Started)/I(stopped) are idempotent actions that will not run
always bounce the service. I(reloaded) will always commands unless necessary. I(restarted) will always bounce the
reload. service. I(reloaded) will always reload.
pattern: pattern:
required: false required: false
description: New in 0.7. If the service does not respond to the version_added: "0.7"
status command, name a substring to look for as would description:
be found in the output of the I(ps) command - If the service does not respond to the status command, name a
as a stand-in for a status result. If the string is substring to look for as would be found in the output of the I(ps)
found, the servie will be assumed to be running. command as a stand-in for a status result. If the string is found,
the servie will be assumed to be running.
enabled: enabled:
required: false required: false
choices: [ yes, no ] choices: [ "yes", "no" ]
description: Whether the service should start on boot. Either description:
I(yes) or I(no). - Whether the service should start on boot.
examples: examples:
- code: service name=httpd state=started - code: service name=httpd state=started
description: Example action from Ansible Playbooks description: Example action from Ansible Playbooks

12
shell

@ -7,8 +7,10 @@ DOCUMENTATION = '''
module: shell module: shell
short_description: Execute commands in nodes. short_description: Execute commands in nodes.
description: description:
- The shell module takes the command name followed by a list of arguments, space delimited. It is almost exactly like the command module but runs the command through the user's configured shell on the remote node. - The shell module takes the command name followed by a list of arguments,
version_added: "0.0.2" space delimited. It is almost exactly like the M(command) module but runs
the command through the user's configured shell on the remote node.
version_added: "0.2"
options: options:
(free form): (free form):
description: description:
@ -29,7 +31,11 @@ examples:
- code: shell somescript.sh >> somelog.txt - code: shell somescript.sh >> somelog.txt
description: Execute the command in remote shell description: Execute the command in remote shell
notes: notes:
- If you want to execute a command securely and predicably, it may be better to use the 'command' module instead. Best practices when writing playbooks will follow the trend of using M(command) unless M(shell) is explicitly required. When running ad-hoc commands, use your best judgement. - If you want to execute a command securely and predicably, it may be
better to use the M(command) module instead. Best practices when writing
playbooks will follow the trend of using M(command) unless M(shell) is
explicitly required. When running ad-hoc commands, use your best
judgement.
requirements: [ ] requirements: [ ]
author: Michael DeHaan author: Michael DeHaan
''' '''

@ -36,7 +36,8 @@ options:
examples: examples:
- code: template src=/mytemplates/foo.j2 dest=/etc/file.conf owner=bin group=wheel mode=0644 - code: template src=/mytemplates/foo.j2 dest=/etc/file.conf owner=bin group=wheel mode=0644
description: "Example from Ansible Playbooks" description: "Example from Ansible Playbooks"
notes: [] notes:
- Since Ansible version 0.9, templates are loaded with C(trim_blocks=True).
requirements: null requirements: null
author: Michael DeHaan author: Michael DeHaan
''' '''

@ -22,7 +22,7 @@ DOCUMENTATION = '''
--- ---
module: user module: user
author: Stephen Fromm author: Stephen Fromm
version_added: 0.0.2 version_added: 0.2
short_description: Manage user accounts short_description: Manage user accounts
requirements: [ useradd, userdel, usermod ] requirements: [ useradd, userdel, usermod ]
description: description:

Loading…
Cancel
Save