2012-03-07 16:35:18 +00:00
< !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" / >
2012-03-12 23:13:19 +00:00
< title > Command Line Examples — Ansible - SSH-Based Configuration Management & Deployment< / title >
2012-03-07 16:35:18 +00:00
< link rel = "stylesheet" href = "_static/default.css" type = "text/css" / >
< link rel = "stylesheet" href = "_static/pygments.css" type = "text/css" / >
2012-03-09 16:44:14 +00:00
< link rel = "stylesheet" href = "_static/bootstrap.css" type = "text/css" / >
< link rel = "stylesheet" href = "_static/bootstrap-sphinx.css" type = "text/css" / >
2012-03-07 16:35:18 +00:00
< script type = "text/javascript" >
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '',
2012-03-12 23:13:19 +00:00
VERSION: '0.01',
2012-03-07 16:35:18 +00:00
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
2012-03-09 16:50:07 +00:00
HAS_SOURCE: false
2012-03-07 16:35:18 +00:00
};
< / 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 >
2012-03-09 16:44:14 +00:00
< script type = "text/javascript" src = "_static/bootstrap-dropdown.js" > < / script >
< script type = "text/javascript" src = "_static/bootstrap-scrollspy.js" > < / script >
2012-03-12 23:13:19 +00:00
< link rel = "top" title = "Ansible - SSH-Based Configuration Management & Deployment" href = "index.html" / >
2012-03-09 03:50:12 +00:00
< link rel = "next" title = "Ansible Modules" href = "modules.html" / >
2012-03-09 16:44:14 +00:00
< 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();
});
}());
2012-03-10 03:31:54 +00:00
< / 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);
})();
2012-03-09 16:44:14 +00:00
< / script >
2012-03-07 16:35:18 +00:00
< / head >
< body >
2012-03-09 16:44:14 +00:00
< 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"
2012-03-31 13:29:31 +00:00
class="dropdown-toggle">Chapter< / a >
2012-03-09 16:44:14 +00:00
< span class = "globaltoc" > < ul class = "current" >
2012-03-10 02:50:00 +00:00
< li class = "toctree-l1" > < a class = "reference internal" href = "gettingstarted.html" > Downloads & Getting Started< / a > < / li >
2012-03-09 16:44:14 +00:00
< 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 >
2012-03-11 19:34:21 +00:00
< li class = "toctree-l1" > < a class = "reference internal" href = "YAMLSyntax.html" > YAML Syntax< / a > < / li >
2012-03-09 16:44:14 +00:00
< li class = "toctree-l1" > < a class = "reference internal" href = "playbooks.html" > Playbooks< / a > < / li >
2012-03-31 02:28:30 +00:00
< li class = "toctree-l1" > < a class = "reference internal" href = "api.html" > API & Integrations< / a > < / li >
2012-03-14 16:50:40 +00:00
< li class = "toctree-l1" > < a class = "reference internal" href = "moduledev.html" > Module Development Guide< / a > < / li >
2012-03-10 02:50:00 +00:00
< li class = "toctree-l1" > < a class = "reference internal" href = "faq.html" > Frequently Asked Questions< / a > < / li >
2012-03-09 16:44:14 +00:00
< li class = "toctree-l1" > < a class = "reference internal" href = "man.html" > Man Pages< / a > < / li >
< / ul >
< / span >
2012-03-31 13:36:37 +00:00
< / 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 & Templating< / a > < / li >
< li > < a class = "reference internal" href = "#managing-packages" > Managing Packages< / 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 >
2012-03-09 16:44:14 +00:00
< / 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 >
2012-03-10 15:39:34 +00:00
2012-03-09 16:44:14 +00:00
< div class = "container" >
2012-03-09 12:42:53 +00:00
< 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. For configuration management and deployments, you’ ll want to pick up on
using < cite > /usr/bin/ansible-playbook< / cite > – the concepts port over directly.< / p >
2012-03-08 18:36:47 +00:00
< 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 >
2012-03-09 03:50:12 +00:00
< p > Let’ s use ansible’ s command line tool to reboot all web servers in Atlanta, 10 at a time:< / p >
2012-03-08 18:36:47 +00:00
< div class = "highlight-python" > < pre > ssh-agent bash
ssh-add ~/.ssh/id_rsa.pub
ansible atlanta -a "/sbin/reboot" -f 10< / pre >
< / div >
< p > The -f 10 specifies the usage of 10 simultaneous processes.< / p >
2012-03-09 23:29:01 +00:00
< div class = "admonition note" >
< p class = "first admonition-title" > Note< / p >
2012-03-31 14:50:47 +00:00
< p class = "last" > -m does not always have to be specified to /usr/bin/ansible because ‘ command’ is the default ansible module< / p >
< / div >
< p > If we want to execute a module using the shell, we can avoid using absolute paths, and can also include
2012-03-17 21:16:31 +00:00
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
2012-03-31 14:50:47 +00:00
module looks like this:< / p >
< div class = "highlight-python" > < pre > ansible raleigh -m shell -a "echo \\$TERM"< / pre >
< / div >
< div class = "admonition note" >
< p class = "first admonition-title" > Note< / p >
< p class = "last" > When using ansible to run commands, and in particular the shell module, be careful of shell quoting rules.< / p >
< / div >
< div class = "admonition note" >
< p class = "first admonition-title" > Note< / p >
2012-03-17 21:16:31 +00:00
< p class = "last" > Note that other than the command < a class = "reference internal" href = "modules.html" > < em > Ansible Modules< / em > < / a > , ansible modules usually do
2012-03-09 23:29:01 +00:00
not work like simple scripts. They make the remote system look like
you state, and run the commands necessary to get it there. This
2012-03-31 14:50:47 +00:00
is commonly referred to as ‘ idempotence’ , 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 >
2012-03-09 23:29:01 +00:00
< / div >
2012-03-08 18:36:47 +00:00
< / div >
2012-03-09 03:50:12 +00:00
< div class = "section" id = "file-transfer-templating" >
< h2 > File Transfer & Templating< a class = "headerlink" href = "#file-transfer-templating" title = "Permalink to this headline" > ¶< / a > < / h2 >
2012-03-09 23:29:01 +00:00
< p > Ansible can SCP lots of files to multiple machines in parallel, and
optionally use them as template sources.< / p >
2012-03-08 18:36:47 +00:00
< p > To just transfer a file directly to many different servers:< / p >
2012-03-31 15:19:35 +00:00
< div class = "highlight-python" > < pre > ansible atlanta -m copy -a "src=/etc/hosts dest=/tmp/hosts"< / pre >
2012-03-08 18:36:47 +00:00
< / div >
2012-03-09 23:29:01 +00:00
< 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
2012-03-16 02:57:10 +00:00
template module to write the files using those templates.< / p >
< p > Templates are written in Jinja2 format. Playbooks (covered elsewhere in the
2012-03-09 23:29:01 +00:00
documentation) will run the setup module for you, making this even
2012-03-16 02:57:10 +00:00
simpler:< / p >
2012-03-08 18:36:47 +00:00
< 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 >
2012-03-07 16:35:18 +00:00
< / div >
2012-03-16 02:57:10 +00:00
< 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 >
2012-03-31 15:19:35 +00:00
< p > The mode, owner, and group arguments can also be used on the copy or template lines.< / p >
2012-03-07 16:35:18 +00:00
< / div >
2012-03-10 16:40:49 +00:00
< 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’ 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 >
2012-03-31 14:40:01 +00:00
< div class = "highlight-python" > < pre > ansible-webservers -m yum -a "pkg=acme state=removed"< / pre >
< / div >
2012-03-10 16:40:49 +00:00
< p > Currently Ansible only has a module for managing packages with yum. You can install
for other package manages using the command module or contribute a module
for other package managers. Stop by the mailing list for info/details.< / p >
< / div >
2012-03-09 03:50:12 +00:00
< 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 >
2012-03-08 18:36:47 +00:00
< p > Deploy your webapp straight from git:< / p >
< div class = "highlight-python" > < pre > ansible webservers -m git -a "repo=git://foo dest=/srv/myapp version=HEAD"< / pre >
2012-03-07 16:35:18 +00:00
< / div >
2012-03-09 23:29:01 +00:00
< 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 >
2012-03-07 16:35:18 +00:00
< / div >
2012-03-09 03:50:12 +00:00
< 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 >
2012-03-10 16:40:49 +00:00
< div class = "highlight-python" > < pre > ansible webservers -m service -a "name=httpd state=started"< / pre >
2012-03-09 03:50:12 +00:00
< / div >
< p > Alternatively, restart a service on all webservers:< / p >
2012-03-10 16:40:49 +00:00
< 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 >
2012-03-09 03:50:12 +00:00
< / div >
< / div >
2012-03-09 12:42:53 +00:00
< 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 >
2012-03-09 23:29:01 +00:00
< 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
2012-03-12 01:09:21 +00:00
hosts, so you won’ t lose track. If you kick hosts and don’ 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 >
2012-03-09 12:42:53 +00:00
< / div >
2012-03-12 01:09:21 +00:00
< p > If you do decide you want to check on the job status later, you can:< / p >
2012-03-12 01:46:05 +00:00
< div class = "highlight-python" > < pre > ansible all -m async_status -a "jid=123456789"< / pre >
2012-03-12 01:09:21 +00:00
< / 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 >
2012-03-31 14:41:29 +00:00
< p > The above example says “ run for 60 minutes max (60*60=3600), poll for status every 60 seconds” .< / p >
< p > Poll mode is smart so all jobs will be started before polling will begin on any machine.
2012-03-12 01:09:21 +00:00
Be sure to use a high enough < cite > – forks< / cite > value if you want to get all of your jobs started
2012-03-12 03:20:55 +00:00
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 >
2012-03-17 21:16:31 +00:00
< p > Any module other than < cite > copy< / cite > or < cite > template< / cite > can be
2012-03-15 00:57:35 +00:00
backgrounded. Typically you’ ll be backgrounding long-running
2012-03-17 21:16:31 +00:00
shell commands or software upgrades only. < a class = "reference internal" href = "playbooks.html" > < em > Playbooks< / em > < / a > also support polling, and have
2012-03-31 14:41:29 +00:00
a simplified syntax for this.< / p >
2012-03-31 13:29:31 +00:00
< 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 & deployment< / dd >
2012-03-31 13:55:37 +00:00
< 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 >
2012-03-31 13:29:31 +00:00
< / dl >
< / div >
2012-03-09 12:42:53 +00:00
< / div >
2012-03-07 16:35:18 +00:00
< / div >
< / div >
2012-03-09 16:44:14 +00:00
< footer class = "footer" >
< div class = "container" >
< p class = "pull-right" > < a href = "#" > Back to top< / a > < / p >
< p >
© Copyright 2012 Michael DeHaan.< br / >
2012-03-17 21:00:41 +00:00
Last updated on Mar 17, 2012.< br / >
2012-03-09 23:29:01 +00:00
Created using < a href = "http://sphinx.pocoo.org/" > Sphinx< / a > 1.0.8.< br / >
2012-03-09 16:44:14 +00:00
< / p >
< / div >
< / footer >
2012-03-07 16:35:18 +00:00
< / body >
< / html >
