examples.html


<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    
    <title>Command Line Examples &mdash; Ansible - SSH-Based Configuration Management &amp; Deployment</title>
    <link rel="stylesheet" href="_static/default.css" type="text/css" />
    <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
    <link rel="stylesheet" href="_static/bootstrap.css" type="text/css" />
    <link rel="stylesheet" href="_static/bootstrap-sphinx.css" type="text/css" />
    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
        URL_ROOT:    '',
        VERSION:     '0.01',
        COLLAPSE_INDEX: false,
        FILE_SUFFIX: '.html',
        HAS_SOURCE:  false
      };
    </script>
    <script type="text/javascript" src="_static/jquery.js"></script>
    <script type="text/javascript" src="_static/underscore.js"></script>
    <script type="text/javascript" src="_static/doctools.js"></script>
    <script type="text/javascript" src="_static/bootstrap-dropdown.js"></script>
    <script type="text/javascript" src="_static/bootstrap-scrollspy.js"></script>
    <link rel="top" title="Ansible - SSH-Based Configuration Management &amp; Deployment" href="index.html" />
    <link rel="next" title="Ansible Modules" href="modules.html" />
    <link rel="prev" title="The Inventory File, Patterns, and Groups" href="patterns.html" />
<script type="text/javascript">
(function () {
  /**
   * Patch TOC list.
   *
   * Will mutate the underlying span to have a correct ul for nav.
   *
   * @param $span: Span containing nested UL's to mutate.
   * @param minLevel: Starting level for nested lists. (1: global, 2: local).
   */
  var patchToc = function ($span, minLevel) {
    var $tocList = $("<ul/>").attr('class', "dropdown-menu"),
      findA;

    // Find all a "internal" tags, traversing recursively.
    findA = function ($elem, level) {
      var level = level || 0,
        $items = $elem.find("> li > a.internal, > ul, > li > ul");

      // Iterate everything in order.
      $items.each(function (index, item) {
        var $item = $(item),
          tag = item.tagName.toLowerCase(),
          pad = 10 + ((level - minLevel) * 10);

        if (tag === 'a' && level >= minLevel) {
          // Add to existing padding.
          $item.css('padding-left', pad + "px");
          // Add list element.
          $tocList.append($("<li/>").append($item));
        } else if (tag === 'ul') {
          // Recurse.
          findA($item, level + 1);
        }
      });
    };

    // Start construction and return.
    findA($span);

    // Wipe out old list and patch in new one.
    return $span.empty("ul").append($tocList);
  };

  $(document).ready(function () {
    // Patch the global and local TOC's to be bootstrap-compliant.
    patchToc($("span.globaltoc"), 1);
    patchToc($("span.localtoc"), 2);

    // Activate.
    $('#topbar').dropdown();
  });
}());
</script>
<script type="text/javascript">

 var _gaq = _gaq || [];
 _gaq.push(['_setAccount', 'UA-29861888-1']);
 _gaq.push(['_trackPageview']);

 (function() {
   var ga = document.createElement('script'); ga.type =
'text/javascript'; ga.async = true;
   ga.src = ('https:' == document.location.protocol ? 'https://ssl' :
'http://www') + '.google-analytics.com/ga.js';
   var s = document.getElementsByTagName('script')[0];
s.parentNode.insertBefore(ga, s);
 })();

</script>

  </head>
  <body>
  <div class="topbar" data-scrollspy="scrollspy" >
    <div class="topbar-inner">
      <div class="container">
        <a class="brand" href="index.html">Ansible</a>
        <ul class="nav">
          
            <li class="dropdown" data-dropdown="dropdown">
  <a href="index.html"
     class="dropdown-toggle">Chapter</a>
  <span class="globaltoc"><ul class="current">
<li class="toctree-l1"><a class="reference internal" href="gettingstarted.html">Downloads &amp; Getting Started</a></li>
<li class="toctree-l1"><a class="reference internal" href="patterns.html">The Inventory File, Patterns, and Groups</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="">Command Line Examples</a></li>
<li class="toctree-l1"><a class="reference internal" href="modules.html">Ansible Modules</a></li>
<li class="toctree-l1"><a class="reference internal" href="YAMLSyntax.html">YAML Syntax</a></li>
<li class="toctree-l1"><a class="reference internal" href="playbooks.html">Playbooks</a></li>
<li class="toctree-l1"><a class="reference internal" href="api.html">API &amp; Integrations</a></li>
<li class="toctree-l1"><a class="reference internal" href="moduledev.html">Module Development Guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="faq.html">Frequently Asked Questions</a></li>
<li class="toctree-l1"><a class="reference internal" href="man.html">Man Pages</a></li>
</ul>
</span>
</li>
            <li class="dropdown" data-dropdown="dropdown">
  <a href="#"
     class="dropdown-toggle">Page</a>
  <span class="localtoc"><ul>
<li><a class="reference internal" href="#">Command Line Examples</a><ul>
<li><a class="reference internal" href="#parallelism-and-shell-commands">Parallelism and Shell Commands</a></li>
<li><a class="reference internal" href="#file-transfer-templating">File Transfer &amp; Templating</a></li>
<li><a class="reference internal" href="#managing-packages">Managing Packages</a></li>
<li><a class="reference internal" href="#users-and-groups">Users and Groups</a></li>
<li><a class="reference internal" href="#deploying-from-source-control">Deploying From Source Control</a></li>
<li><a class="reference internal" href="#managing-services">Managing Services</a></li>
<li><a class="reference internal" href="#time-limited-background-operations">Time Limited Background Operations</a></li>
</ul>
</li>
</ul>
</span>
</li>
          
        </ul>
        <ul class="nav secondary-nav">
          
            
<form class="pull-left" action="search.html" method="get">
  <input type="text" name="q" placeholder="Search" />
  <input type="hidden" name="check_keywords" value="yes" />
  <input type="hidden" name="area" value="default" />
</form>
          
        </ul>
      </div>
    </div>
  </div>


<div class="container">
   
  <div class="section" id="command-line-examples">
<h1>Command Line Examples<a class="headerlink" href="#command-line-examples" title="Permalink to this headline">¶</a></h1>
<p>The following examples show how to use <cite>/usr/bin/ansible</cite> for running ad-hoc tasks.
Start here.</p>
<p>For configuration management and deployments, you&#8217;ll want to pick up on
using <cite>/usr/bin/ansible-playbook</cite> &#8211; the concepts port over directly.
(See <a class="reference internal" href="playbooks.html"><em>Playbooks</em></a> for more information about those)</p>
<div class="section" id="parallelism-and-shell-commands">
<h2>Parallelism and Shell Commands<a class="headerlink" href="#parallelism-and-shell-commands" title="Permalink to this headline">¶</a></h2>
<p>Let&#8217;s use ansible&#8217;s command line tool to reboot all web servers in Atlanta, 10 at a time.  First, let&#8217;s
set up SSH-agent so it can remember our credentials:</p>
<div class="highlight-python"><pre>ssh-agent bash
ssh-add ~/.ssh/id_rsa.pub</pre>
</div>
<p>Now to run the command on all servers in a group, in this case, &#8216;atlanta&#8217;:</p>
<div class="highlight-python"><pre>ansible atlanta -a "/sbin/reboot" -f 10</pre>
</div>
<p>If you didn&#8217;t read about patterns and groups yet, go back and read <a class="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
a <cite>-m</cite> for module name, but the default module name is &#8216;command&#8217;, so we didn&#8217;t need to specify that
here.  We&#8217;ll use <cite>-m</cite> later to run some other <a class="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
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 <a class="reference internal" href="modules.html"><em>Ansible Modules</em></a> page.  The shell
module looks like this:</p>
<div class="highlight-python"><pre>ansible raleigh -m shell -a 'echo $TERM'</pre>
</div>
<p>When running any command with the ansible &#8220;ad hoc&#8221; CLI (as opposed to playbooks), pay particular attention
to shell quoting rules, so the shell doesn&#8217;t eat a variable before it gets passed to Ansible.  For example, u
using double vs single quotes would evaluate the variable on the box you were on.</p>
<p>So far we&#8217;ve been demoing simple command execution, but most ansible modules usually do not work like
simple scripts. They make the remote system look like you state, and run the commands necessary to
get it there.  This is commonly referred to as &#8216;idempotence&#8217;, and is a core design goal of ansible.
However, we also recognize that running ad-hoc commands is equally imporant, so Ansible easily supports both.</p>
</div>
<div class="section" id="file-transfer-templating">
<h2>File Transfer &amp; Templating<a class="headerlink" href="#file-transfer-templating" title="Permalink to this headline">¶</a></h2>
<p>Here&#8217;s another use case for the <cite>/usr/bin/ansible</cite> command line.</p>
<p>Ansible can SCP lots of files to multiple machines in parallel, and
optionally use them as template sources.</p>
<p>To just transfer a file directly to many different servers:</p>
<div class="highlight-python"><pre>ansible atlanta -m copy -a "src=/etc/hosts dest=/tmp/hosts"</pre>
</div>
<p>To use templating, first run the setup module to put the template
variables you would like to use on the remote host. Then use the
template module to write the files using those templates.</p>
<p>Templates are written in Jinja2 format. Playbooks (covered elsewhere in the
documentation) will run the setup module for you, making this even
simpler:</p>
<div class="highlight-python"><pre>ansible webservers -m setup    -a "favcolor=red ntp_server=192.168.1.1"
ansible webservers -m template -a "src=/srv/motd.j2 dest=/etc/motd"
ansible webservers -m template -a "src=/srv/ntp.j2 dest=/etc/ntp.conf"</pre>
</div>
<p>Ansible variables are used in templates by using the name surrounded by double
curly-braces.  If facter or ohai were installed on the remote machine, variables
from those programs can be accessed too, which the appropriate prefix:</p>
<div class="highlight-python"><pre>This is an Ansible variable: {{ favcolor }}
This is a facter variable: {{ facter_hostname }}
This is an ohai variable: {{ ohai_foo }}</pre>
</div>
<p>The <cite>file</cite> module allows changing ownership and permissions on files.  These
same options can be passed directly to the <cite>copy</cite> or <cite>template</cite> modules as well:</p>
<div class="highlight-python"><pre>ansible webservers -m file -a "dest=/srv/foo/a.txt mode=600"
ansible webservers -m file -a "dest=/srv/foo/b.txt mode=600 owner=mdehaan group=mdehaan"</pre>
</div>
<p>The <cite>file</cite> module can also create directories, similar to <cite>mkdir -p</cite>:</p>
<div class="highlight-python"><pre>ansible webservers -m file -a "dest=/path/to/c mode=644 owner=mdehaan group=mdehaan state=directory"</pre>
</div>
<p>As well as delete directories (recursively) and delete files:</p>
<div class="highlight-python"><pre>ansible webservers -m file -a "dest=/path/to/c state=absent"</pre>
</div>
<p>The mode, owner, and group arguments can also be used on the copy or template lines.</p>
</div>
<div class="section" id="managing-packages">
<h2>Managing Packages<a class="headerlink" href="#managing-packages" title="Permalink to this headline">¶</a></h2>
<p>Ensure a package is installed, but don&#8217;t update it:</p>
<div class="highlight-python"><pre>ansible webservers -m yum -a "pkg=acme state=installed"</pre>
</div>
<p>Ensure a package is installed to a specific version:</p>
<div class="highlight-python"><pre>ansible-webservers -m yum -a "pkg=acme-1.5 state=installed"</pre>
</div>
<p>Ensure a package is at the latest version:</p>
<div class="highlight-python"><pre>ansible webservers -m yum -a "pkg=acme state=latest"</pre>
</div>
<p>Ensure a package is not installed:</p>
<div class="highlight-python"><pre>ansible-webservers -m yum -a "pkg=acme state=removed"</pre>
</div>
<p>Currently Ansible only has a module for managing packages with yum.  You can install
for other packages for now using the command module or (better!) contribute a module
for other package managers.  Stop by the mailing list for info/details.</p>
</div>
<div class="section" id="users-and-groups">
<h2>Users and Groups<a class="headerlink" href="#users-and-groups" title="Permalink to this headline">¶</a></h2>
<p>The user module allows easy creation and manipulation of existing user accounts, as well
as removal of user accounts that may exist:</p>
<div class="highlight-python"><pre>ansible all -m user -a "name=foo password=&lt;crypted password here&gt;"

ansible all -m user -a "name=foo state=absent"</pre>
</div>
<p>See the <a class="reference internal" href="modules.html"><em>Ansible Modules</em></a> section for details on all of the available options.</p>
</div>
<div class="section" id="deploying-from-source-control">
<h2>Deploying From Source Control<a class="headerlink" href="#deploying-from-source-control" title="Permalink to this headline">¶</a></h2>
<p>Deploy your webapp straight from git:</p>
<div class="highlight-python"><pre>ansible webservers -m git -a "repo=git://foo.example.org/repo.git dest=/srv/myapp version=HEAD"</pre>
</div>
<p>Since ansible modules can notify change handlers (see
<a class="reference internal" href="playbooks.html"><em>Playbooks</em></a>) it is possible to tell ansible to run specific tasks
when the code is updated, such as deploying Perl/Python/PHP/Ruby
directly from git and then restarting apache.</p>
</div>
<div class="section" id="managing-services">
<h2>Managing Services<a class="headerlink" href="#managing-services" title="Permalink to this headline">¶</a></h2>
<p>Ensure a service is started on all webservers:</p>
<div class="highlight-python"><pre>ansible webservers -m service -a "name=httpd state=started"</pre>
</div>
<p>Alternatively, restart a service on all webservers:</p>
<div class="highlight-python"><pre>ansible webservers -m service -a "name=httpd state=restarted"</pre>
</div>
<p>Ensure a service is stopped:</p>
<div class="highlight-python"><pre>ansible webservers -m service -a "name=httpd state=stopped"</pre>
</div>
</div>
<div class="section" id="time-limited-background-operations">
<h2>Time Limited Background Operations<a class="headerlink" href="#time-limited-background-operations" title="Permalink to this headline">¶</a></h2>
<p>Long running operations can be backgrounded, and their status can be
checked on later. The same job ID is given to the same task on all
hosts, so you won&#8217;t lose track.  If you kick hosts and don&#8217;t want
to poll, it looks like this:</p>
<div class="highlight-python"><pre>ansible all -B 3600 -a "/usr/bin/long_running_operation --do-stuff"</pre>
</div>
<p>If you do decide you want to check on the job status later, you can:</p>
<div class="highlight-python"><pre>ansible all -m async_status -a "jid=123456789"</pre>
</div>
<p>Polling is built-in and looks like this:</p>
<div class="highlight-python"><pre>ansible all -B 3600 -P 60 -a "/usr/bin/long_running_operation --do-stuff"</pre>
</div>
<p>The above example says &#8220;run for 60 minutes max (60*60=3600), poll for status every 60 seconds&#8221;.</p>
<p>Poll mode is smart so all jobs will be started before polling will begin on any machine.
Be sure to use a high enough <cite>&#8211;forks</cite> value if you want to get all of your jobs started
very quickly. After the time limit (in seconds) runs out (<tt class="docutils literal"><span class="pre">-B</span></tt>), the process on
the remote nodes will be terminated.</p>
<p>Any module other than <cite>copy</cite> or <cite>template</cite> can be
backgrounded.  Typically you&#8217;ll be backgrounding long-running
shell commands or software upgrades only.  <a class="reference internal" href="playbooks.html"><em>Playbooks</em></a> also support polling, and have
a simplified syntax for this.</p>
<div class="admonition-see-also admonition seealso">
<p class="first admonition-title">See also</p>
<dl class="last docutils">
<dt><a class="reference internal" href="modules.html"><em>Ansible Modules</em></a></dt>
<dd>A list of available modules</dd>
<dt><a class="reference internal" href="playbooks.html"><em>Playbooks</em></a></dt>
<dd>Using ansible for configuration management &amp; deployment</dd>
<dt><a class="reference external" href="http://groups.google.com/group/ansible-project">Mailing List</a></dt>
<dd>Questions? Help? Ideas?  Stop by the list on Google Groups</dd>
<dt><a class="reference external" href="http://irc.freenode.net">irc.freenode.net</a></dt>
<dd>#ansible IRC chat channel</dd>
</dl>
</div>
</div>
</div>


</div>
<footer class="footer">
  <div class="container">
    <p class="pull-right"><a href="#">Back to top</a></p>
    <p>
        &copy; Copyright 2012 Michael DeHaan.<br/>
      Last updated on Mar 23, 2012.<br/>
      Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.7.<br/>
    </p>
  </div>
</footer>
  </body>
</html>