mirror of
https://github.com/ansible-collections/community.general.git
synced 2024-09-14 20:13:21 +02:00
f2c2786a14
environment (ANSIBLE_{LIBRARY,HOSTS}) if defined.
Update manpages to represent this.
Also update the env-setup script to set ANSIBLE_{LIBRARY,HOSTS}.
235 lines
5.1 KiB
Text
235 lines
5.1 KiB
Text
ansible-modules(5)
|
|
=================
|
|
:doctype:manpage
|
|
:man source: Ansible-modules
|
|
:man version: 0.0.1
|
|
:man manual: Ansible
|
|
|
|
|
|
NAME
|
|
----
|
|
ansible-modules - stock modules shipped with ansible
|
|
|
|
|
|
DESCRIPTION
|
|
-----------
|
|
|
|
Ansible ships with a number of modules that can be executed directly on remote hosts or through
|
|
ansible playbooks.
|
|
|
|
|
|
IDEMPOTENCE
|
|
-----------
|
|
|
|
Most modules other than command are idempotent, meaning they will seek to avoid changes
|
|
unless a change needs to be made. When using ansible playbooks, these modules can
|
|
trigger change events, as described in *ansible-playbooks*(5).
|
|
|
|
Unless otherwise noted, all modules support change hooks.
|
|
|
|
|
|
command
|
|
-------
|
|
|
|
The command module takes the command name followed by a list of arguments, space delimited.
|
|
This is the only module that does not use key=value style parameters.
|
|
|
|
Example usage::
|
|
|
|
/sbin/shutdown -t now
|
|
|
|
This module does not support change hooks.
|
|
|
|
Returns the return code from the program as well as timing information.
|
|
|
|
(Async command running and command execution time limits are in plan.)
|
|
|
|
copy
|
|
----
|
|
|
|
The copy module moves a file on the local box to remote locations.
|
|
|
|
*src=*::
|
|
|
|
Local absolute path to a file to copy to the remote server
|
|
|
|
|
|
*dest=*::
|
|
|
|
Remote absolute path where the file should end up
|
|
|
|
|
|
This module also returns md5sum information about the resultant file.
|
|
|
|
|
|
facter
|
|
------
|
|
|
|
Runs the discovery program 'facter' on the remote system, returning
|
|
JSON data that can be useful for inventory purposes.
|
|
|
|
Requires that 'facter' and 'ruby-json' be installed on the remote end.
|
|
|
|
This module is informative only - it takes no parameters & does not support change hooks,
|
|
nor does it make any changes on the system.
|
|
|
|
|
|
file
|
|
----
|
|
|
|
Ensures the ownership and permissions of files are as desired.
|
|
|
|
Use copy or template first if you need to make sure a file is on the box.
|
|
|
|
In plan.
|
|
|
|
|
|
git
|
|
---
|
|
|
|
Deploys software from git checkouts.
|
|
|
|
*repo=*::
|
|
|
|
git or http protocol address of the repo to checkout
|
|
|
|
*dest=*::
|
|
|
|
where to check it out, an absolute directory path
|
|
|
|
*version=*::
|
|
|
|
what version to check out -- either the git SHA, the literal string 'HEAD', or a tag name
|
|
|
|
|
|
ohai
|
|
----
|
|
|
|
Similar to the facter module, this returns JSON inventory data. Ohai
|
|
data is a bit more verbose and nested than facter.
|
|
|
|
Requires that 'ohai' be installed on the remote end.
|
|
|
|
This module is information only - it takes no parameters & does not
|
|
support change hooks, nor does it make any changes on the system.
|
|
|
|
|
|
ping
|
|
----
|
|
|
|
A trivial test module, this module always returns the integer '1' on
|
|
successful contact.
|
|
|
|
This module does not support change hooks.
|
|
|
|
This module is informative only - it takes no parameters & does not
|
|
support change hooks, nor does it make any changes on the system.
|
|
|
|
|
|
service
|
|
-------
|
|
|
|
Controls services on remote machines.
|
|
|
|
*state=*::
|
|
|
|
Values are 'started', 'stopped', or 'restarted'. Started/stopped
|
|
are idempotent actions that will not run commands unless neccessary.
|
|
'restarted' will always bounce the service
|
|
|
|
|
|
*name=*::
|
|
|
|
The name of the service
|
|
|
|
|
|
setup
|
|
-----
|
|
|
|
Writes a JSON file containing key/value data, for use in templating.
|
|
Call this once before using the template modules, usually as the very
|
|
first step in your playbook.
|
|
|
|
If facter or ohai are installed, variables from these programs will also
|
|
be snapshotted into the JSON file for usage in templating. These variables
|
|
are prefixed with 'facter_' and 'ohai_" so it's easy to tell their source.
|
|
|
|
*metadata=*::
|
|
|
|
Optionally overrides the default JSON file location of /etc/ansible/setup.
|
|
If used, also supply the metadata parameter to 'template'. Change if
|
|
running as a non-root remote user who does not have permissions on /etc/ansible.
|
|
|
|
*anything=*::
|
|
|
|
any other parameters can be named basically anything, and set a key=value
|
|
pair in the JSON file for use in templating.
|
|
|
|
|
|
template
|
|
--------
|
|
|
|
Templates a file out to a remote server. Call the setup module prior to usage.
|
|
|
|
*src=*::
|
|
|
|
path of a Jinja2 formatted template on the local server
|
|
|
|
|
|
*dest*::
|
|
|
|
location to render the template on the remote server
|
|
|
|
|
|
*metadata*::
|
|
|
|
location of a JSON file to use to supply template data. Default is /etc/ansible/setup
|
|
which is the same as the default for the setup module. Change if running as a non-root
|
|
remote user who does not have permissions on /etc/ansible.
|
|
|
|
|
|
This module also returns md5sum information about the resultant file.
|
|
|
|
|
|
user
|
|
----
|
|
|
|
This module is in plan.
|
|
|
|
|
|
yum
|
|
---
|
|
|
|
This module is in plan.
|
|
|
|
|
|
WRITING YOUR OWN MODULES
|
|
------------------------
|
|
|
|
To write your own modules, simply follow the convention of those already available in
|
|
/usr/share/ansible. Modules must return JSON but can be written in any language.
|
|
To support change hooks, modules should return hashes, with a changed: True/False
|
|
element at the top level. Modules can also choose to indicate a failure scenario
|
|
by returning a top level 'failure' element with a True value.
|
|
|
|
|
|
ENVIRONMENT
|
|
-----------
|
|
|
|
ANSIBLE_LIBRARY -- Override the default ansible module library path
|
|
|
|
|
|
AUTHOR
|
|
------
|
|
|
|
Ansible was originally written by Michael DeHaan. See the AUTHORS file
|
|
for a complete list of contributors.
|
|
|
|
SEE ALSO
|
|
--------
|
|
|
|
*ansible*(1)
|
|
|
|
*ansible-playbook*(5)
|
|
|
|
Ansible home page: <https://github.com/mpdehaan/ansible/>
|