mirror of https://github.com/ansible/ansible.git
Tweaking module docs as a result of integrating the new module docs generator
Michael DeHaan
12 years ago
parent
3035394159
commit
dff7b0fdbc
@ -1,55 +1,58 @@
|
||||
.. _file:
|
||||
|
||||
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
|
||||
````````
|
||||
|
||||
.. versionadded:: 0.1
|
||||
|
||||
|
||||
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``.
|
||||
|
||||
|
||||
.. raw:: html
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<td>parameter</td>
|
||||
<td>required</td>
|
||||
<td>default</td>
|
||||
<td>choices</td>
|
||||
<td>comments</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td>dest</td>
|
||||
<td>True</td>
|
||||
<td>[]</td>
|
||||
<td><ul></ul></td>
|
||||
<td>defines the file being managed, unless when used with <em>state=link</em>, and then sets the destination to create a symbolic link to using <em>src</em></td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td>state</td>
|
||||
<td>False</td>
|
||||
<td>file</td>
|
||||
<td><ul><li>file</li><li>link</li><li>directory</li><li>absent</li></ul></td>
|
||||
<td>If directory, all immediate subdirectories will be created if they do not exist. If <em>file</em>, the file will NOT be created if it does not exist, see the <span class='module'>copy</span> or <span class='module'>template</span> module if you want that behavior. If <em>link</em>, the symbolic link will be created or changed. If absent, directories will be recursively deleted, and files or symlinks will be unlinked.</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td>mode</td>
|
||||
<td>False</td>
|
||||
<td></td>
|
||||
<td><ul></ul></td>
|
||||
<td>mode the file or directory should be, such as 0644 as would be fed to <em>chmod</em>. English modes like <b>g+x</b> are not yet supported</td>
|
||||
</tr>
|
||||
|
||||
</table>
|
||||
|
||||
|
||||
.. raw:: html
|
||||
|
||||
|
||||
<p>Example from Ansible Playbooks</p>
|
||||
<p><pre>
|
||||
file path=/etc/foo.conf owner=foo group=foo mode=0644</pre></p>
|
||||
|
||||
<br/>
|
||||
|
||||
|
||||
@ -1,43 +1,87 @@
|
||||
.. _lineinfile:
|
||||
|
||||
lineinfile
|
||||
``````````
|
||||
````````
|
||||
|
||||
.. versionadded:: 0.7
|
||||
|
||||
This module will search a file for a line, and ensure that it is present or
|
||||
absent.
|
||||
|
||||
This is primarily useful when you only want to change a single line in a file.
|
||||
For other cases, see the copy or template modules.
|
||||
|
||||
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
||||
| parameter | required | default | comments |
|
||||
+====================+==========+=========+============================================================================+
|
||||
| state | no | present | 'absent' or 'present' |
|
||||
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
||||
| name | yes | | The file to modify. |
|
||||
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
||||
| regexp | yes | | The regular expression to look for in the file. For state=present, the |
|
||||
| | | | pattern to replace. For state=absent, the pattern of the line to |
|
||||
| | | | remove. |
|
||||
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
||||
| line | maybe | | Required for state=present. The line to insert/replace into the file. Must |
|
||||
| | | | match the value given to 'regexp'. |
|
||||
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
||||
| insertafter | no | EOF | Used with state=present. If specified, the line will be inserted after the |
|
||||
| | | | specified regular expression. Two special values are available: BOF for |
|
||||
| | | | inserting the line at the beginning of the file, and EOF for inserting the |
|
||||
| | | | line at the end of the file. |
|
||||
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
||||
| backup | no | no | Create a backup file including the timestamp information so you can |
|
||||
| | | | get the original file back if you somehow clobbered it incorrectly. |
|
||||
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
||||
|
||||
Example action from Ansible :doc:`playbooks`::
|
||||
|
||||
lineinfile name=/etc/selinux/config regexp=^SELINUX= line=SELINUX=disabled
|
||||
lineinfile name=/etc/sudoers regexp="^#includedir" line="#includedir /etc/sudoers.d"
|
||||
lineinfile name=/etc/httpd/conf/httpd.conf regexp="^ServerName " insertafter="^#ServerName " line="ServerName ansible.example.com"
|
||||
lineinfile name=/etc/sudoers state=absent regexp="^%wheel"
|
||||
|
||||
This module will search a file for a line, and ensure that it is present or absent.
|
||||
This is primarily useful when you want to change a single line in a file only. For other cases, see the ``copy`` or ``template`` modules.
|
||||
|
||||
|
||||
.. raw:: html
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<td>parameter</td>
|
||||
<td>required</td>
|
||||
<td>default</td>
|
||||
<td>choices</td>
|
||||
<td>comments</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td>state</td>
|
||||
<td>False</td>
|
||||
<td>present</td>
|
||||
<td><ul><li>present</li><li>absent</li></ul></td>
|
||||
<td>Whether the line should be there or not.</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td>name</td>
|
||||
<td>True</td>
|
||||
<td></td>
|
||||
<td><ul></ul></td>
|
||||
<td>The file to modify</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td>insertafter</td>
|
||||
<td>False</td>
|
||||
<td>EOF</td>
|
||||
<td><ul><li>BOF</li><li>EOF</li></ul></td>
|
||||
<td>Used with <em>state=present</em>. If specified, the line will be inserted after the specified regular expression. Two special values are available; <code>BOF</code> for inserting the line at the beginning of the file, and <code>EOF</code> for inserting the line at the end of the file.</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td>regexp</td>
|
||||
<td>True</td>
|
||||
<td></td>
|
||||
<td><ul></ul></td>
|
||||
<td>The regular expression to look for in the file. For <em>state=present</em>, the pattern to replace. For <em>state=absent</em>, the pattern of the line to remove.</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td>line</td>
|
||||
<td>False</td>
|
||||
<td></td>
|
||||
<td><ul></ul></td>
|
||||
<td>Required for <em>state=present</em>. The line to insert/replace into the file. Must match the value given to <code>regexp</code>.</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td>backup</td>
|
||||
<td>False</td>
|
||||
<td>False</td>
|
||||
<td><ul></ul></td>
|
||||
<td>Create a backup file including the timestamp information so you can get the original file back if you somehow clobbered it incorrectly.</td>
|
||||
</tr>
|
||||
|
||||
</table>
|
||||
|
||||
|
||||
.. raw:: html
|
||||
|
||||
|
||||
<p></p>
|
||||
<p><pre>
|
||||
lineinfile name=/etc/selinux/config regexp=^SELINUX= line=SELINUX=disabled</pre></p>
|
||||
|
||||
<p></p>
|
||||
<p><pre>
|
||||
lineinfile name=/etc/sudoers state=absent regexp="^%wheel"</pre></p>
|
||||
|
||||
<br/>
|
||||
|
||||
|
||||
@ -1,20 +1,21 @@
|
||||
.. _raw:
|
||||
|
||||
raw
|
||||
```
|
||||
````````
|
||||
|
||||
Executes a low-down and dirty SSH command, not going through the module subsystem.
|
||||
|
||||
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.
|
||||
Executes a low-down and dirty SSH command, not going through the module subsystem. 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 -m raw -a "yum -y install python-simplejson"
|
||||
|
||||
|
||||
.. raw:: html
|
||||
|
||||
|
||||
<p>Example from /usr/bin/ansible to bootstrap a legacy python 2.4 host</p>
|
||||
<p><pre>
|
||||
ansible newhost.example.com -m raw -a "yum -y install python-simplejson"</pre></p>
|
||||
|
||||
<br/>
|
||||
|
||||
|
||||
@ -1,139 +1,21 @@
|
||||
.. _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::
|
||||
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.
|
||||
|
||||
"ansible_facts": {
|
||||
"ansible_all_ipv4_addresses": [
|
||||
"192.168.144.180",
|
||||
"192.168.122.1"
|
||||
],
|
||||
"ansible_all_ipv6_addresses": [
|
||||
"ffff::fff:ffff:ffff:ffff"
|
||||
],
|
||||
"ansible_architecture": "x86_64",
|
||||
"ansible_bios_date": "06/02/2011",
|
||||
"ansible_bios_version": "6.00",
|
||||
"ansible_default_ipv4": {
|
||||
"address": "192.168.144.180",
|
||||
"alias": "eth0",
|
||||
"gateway": "192.168.144.2",
|
||||
"interface": "eth0",
|
||||
"macaddress": "AA:BB:CC:DD:EE:FF",
|
||||
"mtu": "1500",
|
||||
"netmask": "255.255.255.0",
|
||||
"network": "192.168.144.0",
|
||||
"type": "ether"
|
||||
},
|
||||
"ansible_default_ipv6": {},
|
||||
"ansible_distribution": "CentOS",
|
||||
"ansible_distribution_release": "Final",
|
||||
"ansible_distribution_version": "6.2",
|
||||
"ansible_eth0": {
|
||||
"device": "eth0",
|
||||
"ipv4": {
|
||||
"address": "192.168.144.180",
|
||||
"netmask": "255.255.255.0",
|
||||
"network": "192.16.144.0"
|
||||
},
|
||||
"ipv6": [
|
||||
{
|
||||
"address": "ffff::fff:ffff:ffff:ffff",
|
||||
"prefix": "64",
|
||||
"scope": "link"
|
||||
}
|
||||
],
|
||||
"macaddress": "00:0c:29:b6:a2:62",
|
||||
"mtu": "1500",
|
||||
"type": "ether"
|
||||
},
|
||||
"ansible_form_factor": "Other",
|
||||
"ansible_fqdn": "localhost.localdomain",
|
||||
"ansible_hostname": "localhost",
|
||||
"ansible_interfaces": [
|
||||
"lo",
|
||||
"virbr0",
|
||||
"eth0"
|
||||
],
|
||||
"ansible_kernel": "2.6.32-220.2.1.el6.x86_64",
|
||||
"ansible_lo": {
|
||||
"device": "lo",
|
||||
"ipv4": {
|
||||
"address": "127.0.0.1",
|
||||
"netmask": "255.0.0.0",
|
||||
"network": "127.0.0.0"
|
||||
},
|
||||
"ipv6": [
|
||||
{
|
||||
"address": "::1",
|
||||
"prefix": "128",
|
||||
"scope": "host"
|
||||
}
|
||||
],
|
||||
"macaddress": "00:00:00:00:00:00",
|
||||
"mtu": "16436",
|
||||
"type": "loopback"
|
||||
},
|
||||
"ansible_machine": "x86_64",
|
||||
"ansible_memfree_mb": 166,
|
||||
"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_selinux": {
|
||||
"config_mode": "enforcing",
|
||||
"mode": "permissive",
|
||||
"policyvers": 24,
|
||||
"status": "enabled",
|
||||
"type": "targeted"
|
||||
},
|
||||
"ansible_ssh_host_key_dsa_public": "REDACTED",
|
||||
"ansible_ssh_host_key_rsa_public": "REDACTED",
|
||||
"ansible_swapfree_mb": 1933,
|
||||
"ansible_swaptotal_mb": 2015,
|
||||
"ansible_system": "Linux",
|
||||
"ansible_system_vendor": "VMware, Inc.",
|
||||
"ansible_virbr0": {
|
||||
"device": "virbr0",
|
||||
"ipv4": {
|
||||
"address": "192.168.122.1",
|
||||
"netmask": "255.255.255.0",
|
||||
"network": "192.168.122.0"
|
||||
},
|
||||
"macaddress": "AA:BB:CC:DD:EE:FF",
|
||||
"mtu": "1500",
|
||||
"type": "ether"
|
||||
},
|
||||
"ansible_virtualization_role": "guest",
|
||||
"ansible_virtualization_type": "VMware",
|
||||
|
||||
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.
|
||||
.. raw:: html
|
||||
|
||||
Example action from `/usr/bin/ansible`::
|
||||
|
||||
ansible testserver -m setup
|
||||
<p>Obtain facts from all hosts and store them indexed by hostname at /tmp/facts.</p>
|
||||
<p><pre>
|
||||
ansible all -m setup -tree /tmp/facts</pre></p>
|
||||
|
||||
<br/>
|
||||
|
||||
|
||||
@ -1,38 +0,0 @@
|
||||
Who Uses Ansible
|
||||
================
|
||||
|
||||
Ansible is used by all sorts of organizations from hosted web applications, media companies, universities, consultancies, and ISVs -- all over the world. Some of these users include:
|
||||
|
||||
============================================================================================= =====================================================
|
||||
Who They Are What They Do
|
||||
============================================================================================= =====================================================
|
||||
`Alta Language Services <http://www.altalang.com>`_ Language testing, solutions, and translation services
|
||||
`Basho <http://basho.com>`_ Makers of NoSQL key-value store Riak
|
||||
`CatN Hosting <http://catn.com>`_ Scalable Cloud Hosting
|
||||
`Cygate AB <http://cygate.se>`_ IT solutions from Malmö, Sweden
|
||||
`Dag IT Solutions <http://dagit.net>`_ "Enterprise Linux and Beyond"
|
||||
`Duke University Economics <http://duke.edu>`_ Research and Education
|
||||
`The Fedora Project <http://fedoraproject.org>`_ Produces the popular Linux distribution
|
||||
`Four Kitchens <http://fourkitchens.com>`_ "The Drupal Experts"
|
||||
`Lizenzfrei <http://lizenzfrei.at/>`_ Open source consulting and development, Austria
|
||||
`Schmooze Com <http://www.schmoozecom.com/>`_ Creators of Industry-Leading PBX Platforms
|
||||
`Scientific Computing Center, Aristotle Univ. of Thessaloniki <http://www.grid.auth.gr/en/>`_ Grid/Cloud-Based Scientific Computing
|
||||
|
||||
`Skyline.es <http://skylin.es>`_ Realtime Photo Search Engine
|
||||
`Steelhouse <http://steelhouse.com>`_ Behavioral Commerce
|
||||
`Tomorrow Focus Technologies GmbH <http://www.t-f-t.net/>`_ Running some of the biggest web sites in Europe
|
||||
`123i.com.br <http://123i.com.br>`_ Find real estate in Brazil
|
||||
============================================================================================= =====================================================
|
||||
|
||||
and lots of other people (you should see our Google Analytics data). Tweet at `Michael DeHaan <http://twitter.com/laserllama>`_ or `email him <mailto:michael.dehaan@gmail.com>`_ to get your company or project listed here. (It's free!)
|
||||
|
||||
.. seealso::
|
||||
|
||||
`Mailing List <http://groups.google.com/group/ansible-project>`_
|
||||
Several hundred of our closest friends, great for Q&A
|
||||
`irc.freenode.net <http://irc.freenode.net>`_
|
||||
#ansible IRC chat channel
|
||||
`List of Github Contributors <https://github.com/ansible/ansible/graphs/contributors>`_
|
||||
all the awesome folks who have contributed improvements to Ansible
|
||||
`Github Impact Graphs <https://github.com/ansible/ansible/graphs/impact>`_
|
||||
week-to-week source code activity, by contributor
|
||||
File diff suppressed because one or more lines are too long
Loading…
Reference in New Issue