676 lines
38 KiB
ReStructuredText
676 lines
38 KiB
ReStructuredText
Ansible Modules
|
|
===============
|
|
|
|
Ansible ships with a number of modules (called the 'module library')
|
|
that can be executed directly on remote hosts or through :doc:`playbooks`.
|
|
Users can also write their own modules. These modules can control system
|
|
resources, like services, packages, or files (anything really), or
|
|
handle executing system commands.
|
|
|
|
Let's review how we execute three different modules from the command line::
|
|
|
|
ansible webservers -m service -a "name=httpd state=running"
|
|
ansible webservers -m ping
|
|
ansible webservers -m command -a "/sbin/reboot -t now"
|
|
|
|
Each module supports taking arguments. Nearly all modules take ``key=value``
|
|
arguments, space delimited. Some modules take no arguments, and the
|
|
command/shell modules simply take the string of the command you want to run.
|
|
|
|
From playbooks, Ansible modules are executed in a very similar way::
|
|
|
|
- name: reboot the servers
|
|
action: command /sbin/reboot -t now
|
|
|
|
All modules technically return JSON format data, though if you are using the
|
|
command line or playbooks, you don't really need to know much about
|
|
that. If you're writing your own module, you care, and this means you do
|
|
not have to write modules in any particular language -- you get to choose.
|
|
|
|
Most modules other than command are `idempotent`, meaning they will seek
|
|
to avoid changes to the system unless a change needs to be made. When using Ansible
|
|
playbooks, these modules can trigger 'change events'. Unless otherwise
|
|
noted, any given module does support change hooks.
|
|
|
|
Let's see what's available in the Ansible module library, out of the box:
|
|
|
|
.. _apt:
|
|
|
|
apt
|
|
```
|
|
|
|
Manages apt-packages (such as for Debian/Ubuntu).
|
|
|
|
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
|
| parameter | required | default | comments |
|
|
+====================+==========+=========+============================================================================+
|
|
| name | no | | A package name or package specifier with version, like `foo` or `foo=1.0` |
|
|
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
|
| state | no | present | 'absent', 'present', or 'latest'. |
|
|
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
|
| update-cache | no | no | run the equivalent of apt-get update before the operation? |
|
|
| | | | Can be run as part of the package installation or a seperate step |
|
|
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
|
| purge | no | no | Will forge purge of configuration files if state is set to 'removed'. |
|
|
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
|
| default-release | no | | Corresponds to the -t option for apt and sets pin priorities |
|
|
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
|
| install-recommends | no | yes | Corresponds to the --no-install-recommends option for apt, default |
|
|
| | | | behavior works as apt's default behavior, 'no' does not install |
|
|
| | | | recommended packages. Suggested packages are never installed. |
|
|
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
|
|
|
Example action from Ansible :doc:`playbooks`::
|
|
|
|
apt pkg=foo update-cache=yes
|
|
apt pkg=foo state=removed
|
|
apt pkg=foo state=installed
|
|
apt pkg=foo=1.00 state=installed
|
|
apt pkg=nginx state=latest default-release=squeeze-backports update-cache=yes
|
|
apt pkg=openjdk-6-jdk state=latest install-recommends=no
|
|
|
|
.. _assemble:
|
|
|
|
assemble
|
|
````````
|
|
|
|
(new in 0.5) Assembles a configuration file from fragments. Often a particular program will take a single configuration file
|
|
and does not support a conf.d style structure where it is easy to build up the configuration from multiple sources.
|
|
Assmeble will take a directory of files that have already been transferred to the system, and concatenate them
|
|
together to produce a destination file. Files are assembled in string sorting order. Puppet calls this idea
|
|
"fragments".
|
|
|
|
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
|
| parameter | required | default | comments |
|
|
+====================+==========+=========+============================================================================+
|
|
| src | yes | | An already existing directory full of source files |
|
|
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
|
| dest | yes | | A file to create using the concatenation of all of the source files |
|
|
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
|
| OTHERS | | | All arguments that the file module takes may also be used |
|
|
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
|
|
|
Example action from Ansible :doc:`playbooks`::
|
|
|
|
assemble src=/etc/someapp/fragments dest=/etc/someapp/someapp.conf
|
|
|
|
|
|
.. _authorized_key:
|
|
|
|
authorized_key
|
|
``````````````
|
|
|
|
(new in 0.5). Adds or removes an authorized key for a user from a remote host.
|
|
|
|
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
|
| parameter | required | default | comments |
|
|
+====================+==========+=========+============================================================================+
|
|
| user | yes | | Name of the user who should have access to the remote host |
|
|
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
|
| key | yes | | the SSH public key, as a string |
|
|
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
|
| state | no | present | whether the given key should or should not be in the file |
|
|
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
|
|
|
Example action from Ansible :doc:`playbooks`::
|
|
|
|
authorized_key user=charlie key="ssh-dss ASDF1234L+8BTwaRYr/rycsBF1D8e5pTxEsXHQs4iq+mZdyWqlW++L6pMiam1A8yweP+rKtgjK2httVS6GigVsuWWfOd7/sdWippefq74nppVUELHPKkaIOjJNN1zUHFoL/YMwAAAEBALnAsQN10TNGsRDe5arBsW8cTOjqLyYBcIqgPYTZW8zENErFxt7ij3fW3Jh/sCpnmy8rkS7FyK8ULX0PEy/2yDx8/5rXgMIICbRH/XaBy9Ud5bRBFVkEDu/r+rXP33wFPHjWjwvHAtfci1NRBAudQI/98DbcGQw5HmE89CjgZRo5ktkC5yu/8agEPocVjdHyZr7PaHfxZGUDGKtGRL2QzRYukCmWo1cZbMBHcI5FzImvTHS9/8B3SATjXMPgbfBuEeBwuBK5EjL+CtHY5bWs9kmYjmeo0KfUMH8hY4MAXDoKhQ7DhBPIrcjS5jPtoGxIREZjba67r6/P2XKXaCZH6Fc= charlie@example.org 2011-01-17"
|
|
|
|
.. _command:
|
|
|
|
|
|
command
|
|
```````
|
|
|
|
The command module takes the command name followed by a list of
|
|
arguments, space delimited.
|
|
|
|
If you want to run a command through the shell (say you are using
|
|
'<', '>', '|', etc), you actually want the 'shell' module instead.
|
|
The 'command' module is much more secure as it's not affected by the user's environment.
|
|
|
|
The given command will be executed on all selected nodes. It will not
|
|
be processed through the shell, so variables like "$HOME" and
|
|
operations like "<", ">", "|", and "&" will not work. As such, all
|
|
paths to commands must be fully qualified.
|
|
|
|
This module does not support change hooks and returns the return code
|
|
from the program as well as timing information about how long the
|
|
command was running.
|
|
|
|
Example action from Ansible :doc:`playbooks`::
|
|
|
|
command /sbin/shutdown -t now
|
|
|
|
If you only want to run a command if a certain file does not exist, you can do the
|
|
following::
|
|
|
|
command /usr/bin/make_database.sh arg1 arg2 creates=/path/to/database
|
|
|
|
The `creates=` option will not be passed to the executable.
|
|
|
|
|
|
.. _copy:
|
|
|
|
copy
|
|
````
|
|
|
|
The copy module moves a file on the local box to remote locations. In addition to the options
|
|
listed below, the arguments available to the `file` module can also be passed to the copy
|
|
module.
|
|
|
|
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
|
| parameter | required | default | comments |
|
|
+====================+==========+=========+============================================================================+
|
|
| src | yes | | Local path to a file to copy to the remote server, can be absolute or |
|
|
| | | | relative. |
|
|
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
|
| dest | yes | | Remote absolute path where the file should end up |
|
|
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
|
| OTHERS | | | All arguments the file module takes are also supported |
|
|
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
|
|
|
This module also returns md5sum and other information about the resultant file.
|
|
|
|
Example action from Ansible :doc:`playbooks`::
|
|
|
|
copy src=/srv/myfiles/foo.conf dest=/etc/foo.conf owner=foo group=foo mode=0644
|
|
|
|
|
|
.. _facter:
|
|
|
|
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.
|
|
Playbooks do not actually use this module, they use the :ref:`setup`
|
|
module behind the scenes.
|
|
|
|
|
|
fetch
|
|
`````
|
|
|
|
This module works like 'copy', but in reverse. It is used for fetching files
|
|
from remote machines and storing them locally in a file tree, organized by hostname.
|
|
|
|
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
|
| parameter | required | default | comments |
|
|
+====================+==========+=========+============================================================================+
|
|
| src | yes | | The file on the remote system to fetch. This needs to be a file, not |
|
|
| | | | a directory. Recursive fetching may be supported in a later release. |
|
|
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
|
| dest | yes | | A directory to save the file into. For example, if the 'dest' directory |
|
|
| | | | is '/foo', a src file named '/tmp/bar' on host 'host.example.com', would |
|
|
| | | | be saved into '/foo/host.example.com/tmp/bar' |
|
|
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
|
|
|
Example::
|
|
|
|
fetch src=/var/log/messages dest=/home/logtree
|
|
|
|
|
|
file
|
|
````
|
|
|
|
Sets attributes of files, symlinks, and directories, or removes files/symlinks/directories. Many other modules
|
|
support the same options as the file module -- including 'copy', 'template', and 'assmeble'.
|
|
|
|
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
|
| parameter | required | default | comments |
|
|
+====================+==========+=========+============================================================================+
|
|
| dest | yes | | defines the file being managed, unless when used with state=link, and |
|
|
| | | | then sets the destination to create a symbolic link to using 'src' |
|
|
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
|
| state | | file | values are 'file', 'link', 'directory', or 'absent'. If directory, |
|
|
| | | | all immediate subdirectories will be created if they do not exist. If |
|
|
| | | | 'file', the file will NOT be created if it does not exist, see the 'copy' |
|
|
| | | | or 'template' module if you want that behavior. If 'link', the symbolic |
|
|
| | | | link will be created or changed. If absent, directories will be |
|
|
| | | | recursively deleted, and files or symlinks will be unlinked. |
|
|
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
|
| mode | | | mode the file or directory shoudl be, such as 0644 as would be fed to |
|
|
| | | | chmod. English modes like 'g+x' are not yet supported |
|
|
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
|
| owner | | | name of the user that should own the file/directory, as would be fed to |
|
|
| | | | chown |
|
|
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
|
| group | | | name of the group that should own the file/directory, as would be fed to |
|
|
| | | | group |
|
|
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
|
| src | | | path of the file to link to (applies only to state=link) |
|
|
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
|
| seuser | | | user part of SELinux file context. Will default to system policy, if |
|
|
| | | | applicable. If set to '_default', it will use the 'user' portion of the |
|
|
| | | | the policy if available |
|
|
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
|
| serole | | | role part of SELinux file context, '_default' feature works as above. |
|
|
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
|
| setype | | | type part of SELinux file context, '_default' feature works as above |
|
|
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
|
| selevel | | s0 | level part of the SELinux file context. This is the MLS/MCS attribute, |
|
|
| | | | sometimes known as the 'range'. '_default' feature works as above |
|
|
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
|
| context | | | accepts only 'default' as a value. This will restore a file's selinux |
|
|
| | | | context in the policy. Does nothing if no default is available. |
|
|
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
|
|
|
Example action from Ansible :doc:`playbooks`::
|
|
|
|
file path=/etc/foo.conf owner=foo group=foo mode=0644
|
|
file path=/some/path owner=foo group=foo state=directory
|
|
file path=/path/to/delete state=absent
|
|
file src=/file/to/link/to dest=/path/to/symlink owner=foo group=foo state=link
|
|
file path=/some/path state=directory setype=httpd_sys_content_t
|
|
file path=/some/path state=directory context=default
|
|
|
|
.. _git:
|
|
|
|
git
|
|
```
|
|
|
|
Deploys software (or files) from git checkouts.
|
|
|
|
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
|
| parameter | required | default | comments |
|
|
+====================+==========+=========+============================================================================+
|
|
| repo | yes | | git, ssh, or http protocol address of the git repo |
|
|
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
|
| dest | yes | | absolute path of where the repo should be checked out to |
|
|
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
|
| version | | | what version to check out -- either the git SHA, the literal string |
|
|
| | | | 'HEAD', branch name, or a tag name. |
|
|
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
|
| remote | | origin | name of the remote branch |
|
|
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
|
|
|
Example action from Ansible :doc:`playbooks`::
|
|
|
|
git repo=git://foosball.example.org/path/to/repo.git dest=/srv/checkout version=release-0.22
|
|
|
|
.. _group:
|
|
|
|
group
|
|
`````
|
|
|
|
Adds or removes groups.
|
|
|
|
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
|
| parameter | required | default | comments |
|
|
+====================+==========+=========+============================================================================+
|
|
| name | yes | | name of the group |
|
|
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
|
| gid | | | optional git to set for the group |
|
|
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
|
| state | | present | 'absent' or 'present' |
|
|
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
|
| system | | no | if 'yes', indicates that the group being created is a system group. |
|
|
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
|
|
|
To control members of the group, see the users resource.
|
|
|
|
Example action from Ansible :doc:`playbooks`::
|
|
|
|
group name=somegroup state=present
|
|
|
|
.. _ohai:
|
|
|
|
ohai
|
|
````
|
|
|
|
Similar to the :ref:`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.
|
|
|
|
Playbooks should not call the ohai module, playbooks call the
|
|
:ref:`setup` module behind the scenes instead.
|
|
|
|
.. _ping:
|
|
|
|
ping
|
|
````
|
|
|
|
A trivial test module, this module always returns the integer ``1`` on
|
|
successful contact.
|
|
|
|
This module does not support change hooks and is informative only - it
|
|
takes no parameters & does not support change hooks, nor does it make
|
|
any changes on the system.
|
|
|
|
.. _service:
|
|
|
|
raw
|
|
```
|
|
|
|
Executes a low-down and dirty SSH command, not going through the module subsystem.
|
|
This module is new in Ansible 0.4.
|
|
|
|
This is useful and should only be done in two cases. The first case is installing
|
|
python-simplejson on older (python 2.4 and before) hosts that need it as a dependency
|
|
to run modules, since nearly all core modules require it. Another is speaking to any
|
|
devices such as routers that do not have any Python installed. In any other case,
|
|
using the 'shell' or 'command' module is much more appropriate.
|
|
|
|
Arguments given to 'raw' are run directly through the configured remote shell and
|
|
only output is returned. There is no error detection or change handler support
|
|
for this module.
|
|
|
|
Example from `/usr/bin/ansible` to bootstrap a legacy python 2.4 host::
|
|
|
|
ansible newhost.example.com raw -a "yum install python-simplejson"
|
|
|
|
service
|
|
```````
|
|
|
|
Controls services on remote machines.
|
|
|
|
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
|
| parameter | required | default | comments |
|
|
+====================+==========+=========+============================================================================+
|
|
| name | yes | | name of the service |
|
|
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
|
| state | no | started | 'started', 'stopped', 'reloaded', or 'restarted'. Started/stopped are |
|
|
| | | | idempotent actions that will not run commands unless neccessary. |
|
|
| | | | 'restarted' will always bounce the service, 'reloaded' will always reload. |
|
|
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
|
| enabled | no | | Whether the service should start on boot. Either 'yes' or 'no'. |
|
|
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
|
| list | no | | when used as 'list=status', returns the status of the service along with |
|
|
| | | | other results. Primarily useful for /usr/bin/ansible or playbooks with |
|
|
| | | | --verbose. |
|
|
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
|
|
|
Example action from Ansible :doc:`playbooks`::
|
|
|
|
service name=httpd state=started
|
|
service name=httpd state=stopped
|
|
service name=httpd state=restarted
|
|
service name=httpd state=reloaded
|
|
|
|
.. _setup:
|
|
|
|
setup
|
|
`````
|
|
|
|
This module is automatically called by playbooks to gather useful variables about remote hosts that can be used
|
|
in playbooks. It can also be executed directly by /usr/bin/ansible to check what variables are available
|
|
to a host.
|
|
|
|
Ansible provides many 'facts' about the system, automatically.
|
|
|
|
Some of the variables that are supplied are listed below. These in particular
|
|
are from a VMWare Fusion 4 VM running CentOS 6.2::
|
|
|
|
"ansible_architecture": "x86_64",
|
|
"ansible_distribution": "CentOS",
|
|
"ansible_distribution_release": "Final",
|
|
"ansible_distribution_version": "6.2",
|
|
"ansible_eth0": {
|
|
"ipv4": {
|
|
"address": "REDACTED",
|
|
"netmask": "255.255.255.0"
|
|
},
|
|
"ipv6": [
|
|
{
|
|
"address": "REDACTED",
|
|
"prefix": "64",
|
|
"scope": "link"
|
|
}
|
|
],
|
|
"macaddress": "REDACTED"
|
|
},
|
|
"ansible_form_factor": "Other",
|
|
"ansible_fqdn": "localhost.localdomain",
|
|
"ansible_hostname": "localhost",
|
|
"ansible_interfaces": [
|
|
"lo",
|
|
"eth0"
|
|
],
|
|
"ansible_kernel": "2.6.32-220.2.1.el6.x86_64",
|
|
"ansible_lo": {
|
|
"ipv4": {
|
|
"address": "127.0.0.1",
|
|
"netmask": "255.0.0.0"
|
|
},
|
|
"ipv6": [
|
|
{
|
|
"address": "::1",
|
|
"prefix": "128",
|
|
"scope": "host"
|
|
}
|
|
],
|
|
"ansible_machine": "x86_64",
|
|
"ansible_memfree_mb": 89,
|
|
"ansible_memtotal_mb": 993,
|
|
"ansible_processor": [
|
|
"Intel(R) Core(TM) i7-2677M CPU @ 1.80GHz"
|
|
],
|
|
"ansible_processor_cores": "NA",
|
|
"ansible_processor_count": 1,
|
|
"ansible_product_name": "VMware Virtual Platform",
|
|
"ansible_product_serial": "REDACTED",
|
|
"ansible_product_uuid": "REDACTED",
|
|
"ansible_product_version": "None",
|
|
"ansible_python_version": "2.6.6",
|
|
"ansible_product_version": "None",
|
|
"ansible_python_version": "2.6.6",
|
|
"ansible_ssh_host_key_dsa_public": REDACTED",
|
|
"ansible_ssh_host_key_rsa_public": "REDACTED",
|
|
"ansible_swapfree_mb": 1822,
|
|
"ansible_swaptotal_mb": 2015,
|
|
"ansible_system": "Linux",
|
|
"ansible_system_vendor": "VMware, Inc.",
|
|
"ansible_virtualization_role": "None",
|
|
"ansible_virtualization_type": "None",
|
|
|
|
More ansible facts will be added with successive releases.
|
|
|
|
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.
|
|
|
|
All variables are bubbled up to the caller. Using the ansible facts and choosing
|
|
to not install facter and ohai means you can avoid ruby-dependencies
|
|
on your remote systems.
|
|
|
|
Example action from `/usr/bin/ansible`::
|
|
|
|
ansible testserver -m setup
|
|
|
|
|
|
.. _shell:
|
|
|
|
shell
|
|
`````
|
|
|
|
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 given command will be executed on all selected nodes.
|
|
|
|
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 'command'
|
|
unless 'shell' is explicitly required. When running ad-hoc commands,
|
|
use your best judgement.
|
|
|
|
This module does not support change hooks and returns the return code
|
|
from the program as well as timing information about how long the
|
|
command was running.
|
|
|
|
Example action from a playbook::
|
|
|
|
shell somescript.sh >> somelog.txt
|
|
|
|
|
|
.. _template:
|
|
|
|
template
|
|
````````
|
|
|
|
Templates a file out to a remote server.
|
|
|
|
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
|
| parameter | required | default | comments |
|
|
+====================+==========+=========+============================================================================+
|
|
| src | yes | | Path of a Jinja2 formatted template on the local server. This can be |
|
|
| | | | a relative or absolute path. |
|
|
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
|
| dest | yes | | Location to render the template on the remote server |
|
|
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
|
| OTHERS | | | This module also supports all of the arguments to the file module |
|
|
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
|
|
|
Example action from a playbook::
|
|
|
|
template src=/srv/mytemplates/foo.j2 dest=/etc/foo.conf owner=foo group=foo mode=0644
|
|
|
|
|
|
.. _user:
|
|
|
|
user
|
|
````
|
|
|
|
Creates user accounts, manipulates existing user accounts, and removes user accounts.
|
|
|
|
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
|
| parameter | required | default | comments |
|
|
+====================+==========+=========+============================================================================+
|
|
| name | yes | | name of the user to create, remove, or edit |
|
|
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
|
| comment | | | optionally sets the description of the user |
|
|
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
|
| uid | | | optionally sets the uid of the user |
|
|
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
|
| group | | | optionally sets the user's primary group (takes a group name) |
|
|
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
|
| groups | | | puts the user in this comma-delimited list of groups |
|
|
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
|
| append | | no | if 'yes', will only add groups, not set them to just the list in 'groups' |
|
|
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
|
| shell | | | optionally set the user's shell |
|
|
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
|
| createhome | | yes | unless 'no', a home directory will be made for the user |
|
|
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
|
| home | | | sets where the user's homedir should be, if not the default |
|
|
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
|
| password | | | optionally set the user's password to this crypted value. See the user's |
|
|
| | | | example in the github examples directory for what this looks like in a |
|
|
| | | | playbook |
|
|
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
|
| state | | present | when 'absent', removes the user. |
|
|
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
|
| system | | no | only when initially creating, setting this to 'yes' makes the user a |
|
|
| | | | system account. This setting cannot be changed on existing users. |
|
|
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
|
| force | | no | when used with state=absent, behavior is as with userdel --force |
|
|
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
|
| remove | | no | when used with state=remove, behavior is as with userdel --remove |
|
|
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
|
|
|
Example action from Ansible :doc:`playbooks`::
|
|
|
|
user name=mdehaan comment=awesome passwd=awWxVV.JvmdHw createhome=yes
|
|
user name=mdehaan groups=wheel,skynet
|
|
user name=mdehaan state=absent force=yes
|
|
|
|
.. _virt:
|
|
|
|
virt
|
|
````
|
|
|
|
Manages virtual machines supported by libvirt. Requires that libvirt be installed
|
|
on the managed machine.
|
|
|
|
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
|
| parameter | required | default | comments |
|
|
+====================+==========+=========+============================================================================+
|
|
| name | yes | | name of the guest VM being managed |
|
|
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
|
| state | | | 'running', 'shutdown', 'destroyed', or 'undefined'. Note that there may |
|
|
| | | | be some lag for state requests like 'shutdown' since these refer only to |
|
|
| | | | VM states. After starting a guest, it may not be immediately accessible. |
|
|
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
|
| command | | | in addition to state management, various non-idempotent commands are |
|
|
| | | | available. See examples below. |
|
|
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
|
|
|
Example action from Ansible :doc:`playbooks`::
|
|
|
|
virt guest=alpha state=running
|
|
virt guest=alpha state=shutdown
|
|
virt guest=alpha state=destroyed
|
|
virt guest=alpha state=undefined
|
|
|
|
Example guest management commands from /usr/bin/ansible::
|
|
|
|
ansible host -m virt -a "guest=foo command=status"
|
|
ansible host -m virt -a "guest=foo command=pause"
|
|
ansible host -m virt -a "guest=foo command=unpause"
|
|
ansible host -m virt -a "guest=foo command=get_xml"
|
|
ansible host -m virt -a "guest=foo command=autostart"
|
|
|
|
Example host (hypervisor) management commands from /usr/bin/ansible::
|
|
|
|
ansible host -m virt -a "command=freemem"
|
|
ansible host -m virt -a "command=list_vms"
|
|
ansible host -m virt -a "command=info"
|
|
ansible host -m virt -a "command=nodeinfo"
|
|
ansible host -m virt -a "command=virttype"
|
|
|
|
.. _yum:
|
|
|
|
yum
|
|
```
|
|
|
|
Will install, upgrade, remove, and list packages with the yum package manager.
|
|
|
|
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
|
| parameter | required | default | comments |
|
|
+====================+==========+=========+============================================================================+
|
|
| name | yes | | package name, or package specifier with version, like 'name-1.0' |
|
|
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
|
| state | | present | 'present', 'latest', or 'absent'. |
|
|
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
|
| list | | | various non-idempotent commands for usage with /usr/bin/ansible and not |
|
|
| | | | playbooks. See examples below. |
|
|
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
|
|
|
Example action from Ansible :doc:`playbooks`::
|
|
|
|
yum pkg=httpd state=latest
|
|
yum pkg=httpd state=removed
|
|
yum pkg=httpd state=installed
|
|
|
|
|
|
Writing your own modules
|
|
````````````````````````
|
|
|
|
See :doc:`moduledev`.
|
|
|
|
.. seealso::
|
|
|
|
:doc:`examples`
|
|
Examples of using modules in /usr/bin/ansible
|
|
:doc:`playbooks`
|
|
Examples of using modules with /usr/bin/ansible-playbook
|
|
:doc:`moduledev`
|
|
How to write your own modules
|
|
:doc:`api`
|
|
Examples of using modules with the Python API
|
|
`Mailing List <http://groups.google.com/group/ansible-project>`_
|
|
Questions? Help? Ideas? Stop by the list on Google Groups
|
|
`irc.freenode.net <http://irc.freenode.net>`_
|
|
#ansible IRC chat channel
|
|
|