mirror of
https://github.com/ansible-collections/community.general.git
synced 2026-05-06 13:22:48 +00:00
Tweaking module docs as a result of integrating the new module docs generator
This commit is contained in:
Michael DeHaan
@@ -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'.
|
||||
.. versionadded:: 0.1
|
||||
|
||||
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
||||
| 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`::
|
||||
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/>
|
||||
|
||||
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
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
.. _get_url:
|
||||
|
||||
get_url
|
||||
````````````````````````
|
||||
````````
|
||||
|
||||
.. versionadded:: 0.6
|
||||
|
||||
@@ -9,32 +9,58 @@ get_url
|
||||
Downloads files from HTTP, HTTPS, or FTP to the remote server. The remote server must have direct access to the remote resource.
|
||||
|
||||
|
||||
============== ========== ========== ============================================================
|
||||
parameter required default comments
|
||||
============== ========== ========== ============================================================
|
||||
url yes None HTTP, HTTPS, or FTP URL
|
||||
dest yes None absolute path of where to download the file to.If *dest* is a directory, the basename of the file on the remote server will be used. If a directory, *thirsty=yes* must also be set.
|
||||
thirsty no if ``yes``, will download the file every time and replace the file if the contents change. if ``no``, the file will only be downloaded if the destination does not exist. Generally should be ``yes`` only for small local files. prior to 0.6, acts if ``yes`` by default.
|
||||
others all arguments accepted by the ``file`` module also work here
|
||||
============== ========== ========== ============================================================
|
||||
.. raw:: html
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<td>parameter</td>
|
||||
<td>required</td>
|
||||
<td>default</td>
|
||||
<td>choices</td>
|
||||
<td>comments</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td>url</td>
|
||||
<td>True</td>
|
||||
<td>None</td>
|
||||
<td><ul></ul></td>
|
||||
<td>HTTP, HTTPS, or FTP URL</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td>dest</td>
|
||||
<td>True</td>
|
||||
<td>None</td>
|
||||
<td><ul></ul></td>
|
||||
<td>absolute path of where to download the file to.If <em>dest</em> is a directory, the basename of the file on the remote server will be used. If a directory, <em>thirsty=yes</em> must also be set.</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td>thirsty</td>
|
||||
<td>False</td>
|
||||
<td>no</td>
|
||||
<td><ul><li>yes</li><li>no</li></ul></td>
|
||||
<td>if <code>yes</code>, will download the file every time and replace the file if the contents change. if <code>no</code>, the file will only be downloaded if the destination does not exist. Generally should be <code>yes</code> only for small local files. prior to 0.6, acts if <code>yes</code> by default.</td>
|
||||
</tr>
|
||||
|
||||
<tr>
|
||||
<td>others</td>
|
||||
<td>False</td>
|
||||
<td></td>
|
||||
<td><ul></ul></td>
|
||||
<td>all arguments accepted by the <span class='module'>file</span> module also work here</td>
|
||||
</tr>
|
||||
|
||||
</table>
|
||||
|
||||
|
||||
.. raw:: html
|
||||
|
||||
|
||||
FIXME: examples!
|
||||
<p>Example from Ansible Playbooks</p>
|
||||
<p><pre>
|
||||
get_url url=http://example.com/path/file.conf dest=/etc/foo.conf mode=0440</pre></p>
|
||||
|
||||
<br/>
|
||||
|
||||
|
||||
.. note::
|
||||
|
||||
|
||||
This module doesn't support proxies or passwords.
|
||||
|
||||
Also see the ``template`` module.
|
||||
|
||||
|
||||
Example action from Ansible :doc:`playbooks`::
|
||||
|
||||
|
||||
get_url url=http://example.com/path/file.conf dest=/etc/foo.conf mode=0440
|
||||
|
||||
|
||||
@@ -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.
|
||||
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.
|
||||
|
||||
+--------------------+----------+---------+----------------------------------------------------------------------------+
|
||||
| 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`::
|
||||
.. raw:: html
|
||||
|
||||
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"
|
||||
<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/>
|
||||
|
||||
|
||||
Reference in New Issue
Block a user