@@ -268,7 +268,7 @@ of these options via an external inventory system.</p>
...
@@ -268,7 +268,7 @@ of these options via an external inventory system.</p>
<p>If you are familiar with Puppet terminology, this concept is basically the same as ‘external nodes’, with the slight difference that it also defines which hosts are managed.</p>
<p>If you are familiar with Puppet terminology, this concept is basically the same as ‘external nodes’, with the slight difference that it also defines which hosts are managed.</p>
<divclass="section"id="script-conventions">
<divclass="section"id="script-conventions">
<h3>Script Conventions<aclass="headerlink"href="#script-conventions"title="Permalink to this headline">¶</a></h3>
<h3>Script Conventions<aclass="headerlink"href="#script-conventions"title="Permalink to this headline">¶</a></h3>
<p>When the external node script is called with no arguments, the script must return a JSON hash/dictionary of all the groups to be managed, with a list of each host/IP as the value for each hash/dictionary element, like so:</p>
<p>When the external node script is called with the single argument ‘–list’, the script must return a JSON hash/dictionary of all the groups to be managed, with a list of each host/IP as the value for each hash/dictionary element, like so:</p>
@@ -276,8 +276,8 @@ of these options via an external inventory system.</p>
...
@@ -276,8 +276,8 @@ of these options via an external inventory system.</p>
<spanclass="p">}</span>
<spanclass="p">}</span>
</pre></div>
</pre></div>
</div>
</div>
<p>When called with a single argument, the name of a host from above, the script must return either an empty JSON
<p>When called with the arguments ‘–host <hostname>’ (where <hostname> is a host from above), the script must return either an empty JSON
hash/dictionary, or a list of key/value variables to make available to templates. Returning variables is optional,
hash/dictionary, or a list of key/value variables to make available to templates or playbooks. Returning variables is optional,
if the script does not wish to do this, returning an empty hash/dictionary is the way to go:</p>
if the script does not wish to do this, returning an empty hash/dictionary is the way to go:</p>
@@ -194,21 +194,28 @@ set up SSH-agent so it can remember our credentials:</p>
...
@@ -194,21 +194,28 @@ set up SSH-agent so it can remember our credentials:</p>
<divclass="highlight-python"><pre>ssh-agent bash
<divclass="highlight-python"><pre>ssh-agent bash
ssh-add ~/.ssh/id_rsa.pub</pre>
ssh-add ~/.ssh/id_rsa.pub</pre>
</div>
</div>
<p>Now to run the command on all servers in a group, in this case, ‘atlanta’:</p>
<p>If you don’t want to use ssh-agent and want to instead SSH with a password instead of keys, you can with
–ask-pass (-k), but it’s much better to just use ssh-agent.</p>
<p>Now to run the command on all servers in a group, in this case, ‘atlanta’, in 10 parallel forks:</p>
<divclass="highlight-python"><pre>ansible atlanta -a "/sbin/reboot" -f 10</pre>
<divclass="highlight-python"><pre>ansible atlanta -a "/sbin/reboot" -f 10</pre>
</div>
</div>
<p>If you want to run commands as a different user than root:</p>
<p>If you want to run commands as a different user than root, it looks like this:</p>
<divclass="highlight-python"><pre>ansible atlanta -a "/usr/bin/foo" -u yourname</pre>
<divclass="highlight-python"><pre>ansible atlanta -a "/usr/bin/foo" -u yourname</pre>
</div>
</div>
<p>If you want to run commands through sudo:</p>
<p>If you want to run commands through sudo:</p>
<divclass="highlight-python"><pre>ansible atlanta -a "/usr/bin/foo" -u yourname --sudo [--ask-sudo-pass]</pre>
<divclass="highlight-python"><pre>ansible atlanta -a "/usr/bin/foo" -u yourname --sudo [--ask-sudo-pass]</pre>
</div>
</div>
<p>Use –ask-sudo-pass (-K) if you are not using passwordless sudo.</p>
<p>Use –ask-sudo-pass (-K) if you are not using passwordless sudo. This will interactively prompt
you for the password to use. Use of passwordless sudo makes things easier to automate, but it’s
not required.</p>
<p>It is also possible to sudo to a user other than root using –sudo-user (-U):</p>
<divclass="highlight-python"><pre>ansible atlanta -a "/usr/bin/foo" -u yourname -U otheruser [--ask-sudo-pass]</pre>
</div>
<p>Ok, so those are basics. If you didn’t read about patterns and groups yet, go back and read <aclass="reference internal"href="patterns.html"><em>The Inventory File, Patterns, and Groups</em></a>.</p>
<p>Ok, so those are basics. If you didn’t read about patterns and groups yet, go back and read <aclass="reference internal"href="patterns.html"><em>The Inventory File, Patterns, and Groups</em></a>.</p>
<p>The -f 10 in the above specifies the usage of 10 simultaneous processes. Normally commands also take
<p>The -f 10 in the above specifies the usage of 10 simultaneous processes. Normally commands also take
a <cite>-m</cite> for module name, but the default module name is ‘command’, so we didn’t need to specify that
a <cite>-m</cite> for module name, but the default module name is ‘command’, so we didn’t need to specify that
here. We’ll use <cite>-m</cite> later to run some other <aclass="reference internal"href="modules.html"><em>Ansible Modules</em></a>.</p>
all of the time. We’ll use <cite>-m</cite> in later examples to run some other <aclass="reference internal"href="modules.html"><em>Ansible Modules</em></a>.</p>
<p>The command module requires absolute paths and does not support shell variables. If we want to
<p>Note that the command module requires absolute paths and does not support shell variables. If we want to
execute a module using the shell, we can do those things, and also use pipe and redirection operators.
execute a module using the shell, we can do those things, and also use pipe and redirection operators.
Read more about the differences on the <aclass="reference internal"href="modules.html"><em>Ansible Modules</em></a> page. The shell
Read more about the differences on the <aclass="reference internal"href="modules.html"><em>Ansible Modules</em></a> page. The shell
module looks like this:</p>
module looks like this:</p>
...
@@ -373,7 +380,7 @@ a simplified syntax for this.</p>
...
@@ -373,7 +380,7 @@ a simplified syntax for this.</p>
<h3>Via RPM<aclass="headerlink"href="#via-rpm"title="Permalink to this headline">¶</a></h3>
<h3>Via RPM<aclass="headerlink"href="#via-rpm"title="Permalink to this headline">¶</a></h3>
<p>In the near future, pre-built packages will be available through your
<p>RPMs for the last Ansible release are available for <aclass="reference external"href="http://fedoraproject.org/wiki/EPEL">EPEL</a> 6 and currently supported
distribution. Until that time, you can use the <ttclass="docutils literal"><spanclass="pre">make</span><spanclass="pre">rpm</span></tt> command to
Fedora distributions.</p>
<blockquote>
<div># install the epel-release RPM if needed on CentOS, RHEL, or Scientific Linux
$ sudo yum install ansible</div></blockquote>
<p>You can also use the <ttclass="docutils literal"><spanclass="pre">make</span><spanclass="pre">rpm</span></tt> command to
<liclass="toctree-l2"><aclass="reference internal"href="patterns.html#groups-of-groups">Groups of Groups</a></li>
<liclass="toctree-l2"><aclass="reference internal"href="patterns.html#groups-of-groups-and-group-variables">Groups of Groups, and Group Variables</a></li>
@@ -225,11 +226,11 @@ noted, any given module does support change hooks.</p>
...
@@ -225,11 +226,11 @@ noted, any given module does support change hooks.</p>
<p>Manages apt-packages (such as for Debian/Ubuntu).</p>
<p>Manages apt-packages (such as for Debian/Ubuntu).</p>
<p><em>pkg</em>:</p>
<p><em>pkg</em>:</p>
<ulclass="simple">
<ulclass="simple">
<li>A package name or package specifier with version, like foo=1.0</li>
<li>A package name or package specifier with version, like <cite>foo</cite>, or <cite>foo=1.0</cite> to install a specific version of the foo package.</li>
</ul>
</ul>
<p><em>state</em>:</p>
<p><em>state</em>:</p>
<ulclass="simple">
<ulclass="simple">
<li>Can be either ‘installed’, ‘removed’, or ‘latest’. The default is ‘installed’.</li>
<li>Can be either ‘installed’, ‘removed’, or ‘latest’. The default is ‘installed’. (In 0.4 and later, the aliases ‘absent’ and ‘present’ can also be used. They correspond with ‘removed’ and ‘installed’)</li>
<li>either ‘absent’, or ‘present’. ‘present’ is the default.</li>
<li>either ‘absent’, or ‘present’. ‘present’ is the default.</li>
</ul>
</ul>
<p><em>system</em>:</p>
<ulclass="simple">
<li>(new in 0.4) Indicates the group (when being created), should be a system group. This does not allow changing groups from and to system groups. Value is ‘yes’ or ‘no’, default is ‘no’.</li>
</ul>
<p>To control members of the group, see the users resource.</p>
<p>To control members of the group, see the users resource.</p>
<p>Example action from Ansible <aclass="reference internal"href="playbooks.html"><em>Playbooks</em></a>:</p>
<p>Example action from Ansible <aclass="reference internal"href="playbooks.html"><em>Playbooks</em></a>:</p>
takes no parameters & does not support change hooks, nor does it make
takes no parameters & does not support change hooks, nor does it make
any changes on the system.</p>
any changes on the system.</p>
</div>
</div>
<divclass="section"id="service">
<divclass="section"id="raw">
<spanid="id9"></span><h2>service<aclass="headerlink"href="#service"title="Permalink to this headline">¶</a></h2>
<spanid="service"></span><h2>raw<aclass="headerlink"href="#raw"title="Permalink to this headline">¶</a></h2>
<p>Executes a low-down and dirty SSH command, not going through the module subsystem.
This module is new in Ansible 0.4.</p>
<p>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.</p>
<p>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.</p>
<p>Example from <cite>/usr/bin/ansible</cite> to bootstrap a legacy python 2.4 host:</p>
<blockquote>
<div>ansible newhost.example.com raw -a “yum install python-simplejson”</div></blockquote>
</div>
<divclass="section"id="id9">
<h2>service<aclass="headerlink"href="#id9"title="Permalink to this headline">¶</a></h2>
<p>Controls services on remote machines.</p>
<p>Controls services on remote machines.</p>
<p><em>state</em>:</p>
<p><em>state</em>:</p>
<ulclass="simple">
<ulclass="simple">
...
@@ -452,6 +477,15 @@ any changes on the system.</p>
...
@@ -452,6 +477,15 @@ any changes on the system.</p>
Started/stopped are idempotent actions that will not run commands
Started/stopped are idempotent actions that will not run commands
unless necessary. <ttclass="docutils literal"><spanclass="pre">restarted</span></tt> will always bounce the service.</li>
unless necessary. <ttclass="docutils literal"><spanclass="pre">restarted</span></tt> will always bounce the service.</li>
</ul>
</ul>
<p><em>enabled</em>:</p>
<ulclass="simple">
<li>(new in 0.4) Whether the service should start on boot. Either ‘yes’ or ‘no’.
Uses chkconfig or updates-rc.d as appropriate.</li>
</ul>
<p><em>list</em>:</p>
<ulclass="simple">
<li>(new in 0.4) When used with the value ‘status’, returns the status of the service along with other results. This is primarily useful for /usr/bin/ansible, and not meaningful for playbooks.</li>
</ul>
<p><em>name</em>:</p>
<p><em>name</em>:</p>
<ulclass="simple">
<ulclass="simple">
<li>The name of the service.</li>
<li>The name of the service.</li>
...
@@ -636,6 +670,10 @@ be a relative or absolute path.</li>
...
@@ -636,6 +670,10 @@ be a relative or absolute path.</li>
<ulclass="simple">
<ulclass="simple">
<li>Defaults to ‘present’. When ‘absent’, the user account will be removed if present. Optionally additional removal behaviors can be set with the ‘force’ or ‘remove’ parameter values (see below).</li>
<li>Defaults to ‘present’. When ‘absent’, the user account will be removed if present. Optionally additional removal behaviors can be set with the ‘force’ or ‘remove’ parameter values (see below).</li>
</ul>
</ul>
<p><em>system</em>:</p>
<ulclass="simple">
<li>(new in 0.4) Indicates the user (when being created), should be a system account. This does not allow changing users from and to system accounts. Value is ‘yes’ or ‘no’, default is ‘no’.</li>
</ul>
<p><em>force</em>:</p>
<p><em>force</em>:</p>
<ulclass="simple">
<ulclass="simple">
<li>When used with a state of ‘absent’, the behavior denoted in the ‘userdel’ manpage for <ttclass="docutils literal"><spanclass="pre">--force</span></tt> is also used when removing the user. Value is ‘yes’ or ‘no’, default is ‘no’.</li>
<li>When used with a state of ‘absent’, the behavior denoted in the ‘userdel’ manpage for <ttclass="docutils literal"><spanclass="pre">--force</span></tt> is also used when removing the user. Value is ‘yes’ or ‘no’, default is ‘no’.</li>
...
@@ -696,13 +734,14 @@ ansible host -m virt -a "command=virttype"</pre>
...
@@ -696,13 +734,14 @@ ansible host -m virt -a "command=virttype"</pre>
</ul>
</ul>
<p><em>state</em>:</p>
<p><em>state</em>:</p>
<ulclass="simple">
<ulclass="simple">
<li>Can be either ‘installed’, ‘latest’, or ‘removed’. The default is ‘installed’.</li>
<li>Can be either ‘installed’, ‘latest’, or ‘removed’. The default is ‘installed’. (In 0.4 and later, the aliases ‘absent’ and ‘present’ can also be used. They correspond with ‘removed’ and ‘installed’)</li>
</ul>
</ul>
<p><em>list</em>:</p>
<p><em>list</em>:</p>
<ulclass="simple">
<ulclass="simple">
<li>When ‘list’ is supplied instead of ‘state’, the yum module can list
<li>When ‘list’ is supplied instead of ‘state’, the yum module can list
various configuration attributes. Values include ‘installed’, ‘updates’,
various configuration attributes. Values include ‘installed’, ‘updates’,
‘available’, ‘repos’, or any package specifier.</li>
‘available’, ‘repos’, or any package specifier. (This is more intended for
use with /usr/bin/ansible or the API, not playbooks.)</li>
</ul>
</ul>
<p>Example action from Ansible <aclass="reference internal"href="playbooks.html"><em>Playbooks</em></a>:</p>
<p>Example action from Ansible <aclass="reference internal"href="playbooks.html"><em>Playbooks</em></a>:</p>
<pclass="last">It is not possible to target a host not in the inventory file, unless using playbooks with –override-hosts. More on that later. This is a safety feature.</p>
</div>
<p>Easy enough. See <aclass="reference internal"href="examples.html"><em>Command Line Examples</em></a> and then <aclass="reference internal"href="playbooks.html"><em>Playbooks</em></a> for how to do things to selected hosts.</p>
<p>Easy enough. See <aclass="reference internal"href="examples.html"><em>Command Line Examples</em></a> and then <aclass="reference internal"href="playbooks.html"><em>Playbooks</em></a> for how to do things to selected hosts.</p>
