mirror of https://github.com/ansible/ansible.git
Subtree merge of ansible-docs
Michael DeHaan
12 years ago
commit
d6e4b1bf5b
@ -0,0 +1,13 @@
|
||||
# Old compiled python stuff
|
||||
*.py[co]
|
||||
# package building stuff
|
||||
build
|
||||
# Emacs backup files...
|
||||
*~
|
||||
.\#*
|
||||
.doctrees
|
||||
# Generated docs stuff
|
||||
ansible*.xml
|
||||
.buildinfo
|
||||
objects.inv
|
||||
.doctrees
|
||||
@ -0,0 +1,34 @@
|
||||
#!/usr/bin/make
|
||||
SITELIB = $(shell python -c "from distutils.sysconfig import get_python_lib; print get_python_lib()")
|
||||
FORMATTER=../ansible/hacking/module_formatter.py
|
||||
|
||||
all: clean docs
|
||||
|
||||
docs: clean modules
|
||||
./build-site.py
|
||||
|
||||
viewdocs: clean
|
||||
./build-site.py view
|
||||
|
||||
htmldocs:
|
||||
./build-site.py rst
|
||||
|
||||
clean:
|
||||
-rm -f .buildinfo
|
||||
-rm -f *.inv
|
||||
-rm -rf *.doctrees
|
||||
@echo "Cleaning up byte compiled python stuff"
|
||||
find . -regex ".*\.py[co]$$" -delete
|
||||
@echo "Cleaning up editor backup files"
|
||||
find . -type f \( -name "*~" -or -name "#*" \) -delete
|
||||
find . -type f \( -name "*.swp" \) -delete
|
||||
|
||||
.PHONEY: docs clean
|
||||
|
||||
#modules: $(FORMATTER) ../ansible/hacking/templates/rst.j2
|
||||
# $(FORMATTER) -t rst --module-dir=../ansible/library -o rst/modules/
|
||||
|
||||
modules: $(FORMATTER) ../ansible/hacking/templates/rst.j2
|
||||
$(FORMATTER) -t rst --template-dir=../ansible/hacking/templates --module-dir=../ansible/library -o rst/modules/ --includes-file=rst/modules/_list.rst
|
||||
|
||||
|
||||
@ -0,0 +1,23 @@
|
||||
Homepage and documentation source for the Ansible
|
||||
=================================================
|
||||
|
||||
This project hosts the source behind [ansible.cc/docs](http://ansible.cc/docs)
|
||||
|
||||
Contributions to the documentation are welcome. To make changes, submit a pull request
|
||||
that changes the restructured text files in the "rst/" directory only, and Michael can
|
||||
do a docs build and push the static files.
|
||||
|
||||
If you do not want to learn RST format (ReStructured Text), you can also file issues
|
||||
on the documentation project.
|
||||
|
||||
Note that module documentation can actually be generated from a DOCUMENTATION docstring
|
||||
in the modules directory, so corrections to modules written as much need to be made
|
||||
in the main project in the module source, rather than in the documentation for the module.
|
||||
|
||||
Author
|
||||
======
|
||||
|
||||
Michael DeHaan -- michael.dehaan@gmail.com
|
||||
|
||||
[http://michaeldehaan.net](http://michaeldehaan.net/)
|
||||
|
||||
@ -0,0 +1,276 @@
|
||||
|
||||
<!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>YAML Syntax — Ansible Documentation</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="shortcut icon" href="_static/favicon.ico"/>
|
||||
<link rel="top" title="Ansible Documentation" href="index.html" />
|
||||
<link rel="next" title="Playbooks" href="playbooks.html" />
|
||||
<link rel="prev" title="Ansible Modules" href="modules.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>
|
||||
|
||||
<script type="text/javascript">
|
||||
(function() {
|
||||
var po = document.createElement('script'); po.type = 'text/javascript'; po.async = true;
|
||||
po.src = 'https://apis.google.com/js/plusone.js';
|
||||
var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(po, s);
|
||||
})();
|
||||
</script>
|
||||
|
||||
<script>(function(d, s, id) {
|
||||
var js, fjs = d.getElementsByTagName(s)[0];
|
||||
if (d.getElementById(id)) return;
|
||||
js = d.createElement(s); js.id = id;
|
||||
js.src = "//connect.facebook.net/en_US/all.js#xfbml=1";
|
||||
fjs.parentNode.insertBefore(js, fjs);
|
||||
}(document, 'script', 'facebook-jssdk'));</script>
|
||||
|
||||
</head>
|
||||
<body>
|
||||
<div class="topbar" data-scrollspy="scrollspy" >
|
||||
<div class="topbar-inner">
|
||||
<div class="container">
|
||||
<a class="brand" href="index.html">Ansible Documentation</a>
|
||||
<ul class="nav">
|
||||
|
||||
<li><a href="/">Home</A>
|
||||
<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">Getting Started</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="patterns.html">Inventory & Patterns</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="examples.html">Command Line Examples And Next Steps</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="modules.html">Ansible Modules</a></li>
|
||||
<li class="toctree-l1 current"><a class="current reference internal" href="">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="playbooks2.html">Advanced Playbooks</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="bestpractices.html">Best Practices</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="api.html">API & Integrations</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="moduledev.html">Module Development</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="#">YAML Syntax</a><ul>
|
||||
<li><a class="reference internal" href="#yaml-basics">YAML Basics</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="yaml-syntax">
|
||||
<h1>YAML Syntax<a class="headerlink" href="#yaml-syntax" title="Permalink to this headline">¶</a></h1>
|
||||
<p>This page provides a basic overview of correct YAML syntax, which is how Ansible
|
||||
playbooks (our configuration management language) are expressed.</p>
|
||||
<p>We use YAML because it is easier to read and write for humans than other common
|
||||
data formats like XML or JSON. Further, there are libraries available for reading
|
||||
and writing YAML in most programming languages.</p>
|
||||
<p>You may also wish to read <a class="reference internal" href="playbooks.html"><em>Playbooks</em></a> at the same time to see how this
|
||||
is used in practice.</p>
|
||||
<div class="section" id="yaml-basics">
|
||||
<h2>YAML Basics<a class="headerlink" href="#yaml-basics" title="Permalink to this headline">¶</a></h2>
|
||||
<p>For <cite>ansible</cite>, nearly every YAML file starts with a list.
|
||||
Each item in the list is a list of key/value pairs, commonly
|
||||
called a “hash” or a “dictionary”. So, we need to know how
|
||||
to write lists and dictionaries in YAML.</p>
|
||||
<p>There’s another small quirk to YAML. All YAML files (regardless of their association with
|
||||
<cite>ansible</cite> or not) should start with <tt class="docutils literal"><span class="pre">---</span></tt>. This is just a YAML
|
||||
format thing that means “this is the start of a document”.</p>
|
||||
<p>All members of a list are lines beginning at the same indentation level starting
|
||||
with a <tt class="docutils literal"><span class="pre">-</span></tt> (dash) character:</p>
|
||||
<div class="highlight-python"><pre>---
|
||||
# A list of tasty fruits
|
||||
- Apple
|
||||
- Orange
|
||||
- Strawberry
|
||||
- Mango</pre>
|
||||
</div>
|
||||
<p>A dictionary is represented in a simple <tt class="docutils literal"><span class="pre">key:</span></tt> and <tt class="docutils literal"><span class="pre">value</span></tt> form:</p>
|
||||
<div class="highlight-python"><pre>---
|
||||
# An employee record
|
||||
name: John Eckersberg
|
||||
job: Developer
|
||||
skill: Elite</pre>
|
||||
</div>
|
||||
<p>Dictionaries can also be represented in an abbreviated form if you really want to:</p>
|
||||
<div class="highlight-python"><pre>---
|
||||
# An employee record
|
||||
{name: John Eckersberg, job: Developer, skill: Elite}</pre>
|
||||
</div>
|
||||
<p id="truthiness">Ansible doesn’t really use these too much, but you can also specify a
|
||||
boolean value (true/false) in several forms:</p>
|
||||
<div class="highlight-python"><pre>---
|
||||
knows_oop: True
|
||||
likes_emacs: TRUE
|
||||
uses_cvs: false</pre>
|
||||
</div>
|
||||
<p>Let’s combine what we learned so far in an arbitary YAML example. This really
|
||||
has nothing to do with Ansible, but will give you a feel for the format:</p>
|
||||
<div class="highlight-python"><pre>---
|
||||
# An employee record
|
||||
name: John Eckersberg
|
||||
job: Developer
|
||||
skill: Elite
|
||||
employed: True
|
||||
foods:
|
||||
- Apple
|
||||
- Orange
|
||||
- Strawberry
|
||||
- Mango
|
||||
languages:
|
||||
ruby: Elite
|
||||
python: Elite
|
||||
dotnet: Lame</pre>
|
||||
</div>
|
||||
<p>That’s all you really need to know about YAML to get started writing
|
||||
<cite>Ansible</cite> playbooks.</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="playbooks.html"><em>Playbooks</em></a></dt>
|
||||
<dd>Learn what playbooks can do and how to write/run them.</dd>
|
||||
<dt><a class="reference external" href="http://yamllint.com/">YAMLLint</a></dt>
|
||||
<dd>YAML Lint (online) helps you debug YAML syntax if you are having problems</dd>
|
||||
<dt><a class="reference external" href="https://github.com/ansible/ansible/tree/devel/examples/playbooks">Github examples directory</a></dt>
|
||||
<dd>Complete playbook files from the github project source</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>
|
||||
|
||||
|
||||
<br/>
|
||||
</div>
|
||||
<footer class="footer">
|
||||
<div class="container">
|
||||
<p>
|
||||
<p>
|
||||
© Copyright 2012 Michael DeHaan.<br/>
|
||||
Last updated on Oct 08, 2012.<br/>
|
||||
</p>
|
||||
</div>
|
||||
</footer>
|
||||
</body>
|
||||
</html>
|
||||
@ -0,0 +1,540 @@
|
||||
/*
|
||||
* basic.css
|
||||
* ~~~~~~~~~
|
||||
*
|
||||
* Sphinx stylesheet -- basic theme.
|
||||
*
|
||||
* :copyright: Copyright 2007-2011 by the Sphinx team, see AUTHORS.
|
||||
* :license: BSD, see LICENSE for details.
|
||||
*
|
||||
*/
|
||||
|
||||
/* -- main layout ----------------------------------------------------------- */
|
||||
|
||||
div.clearer {
|
||||
clear: both;
|
||||
}
|
||||
|
||||
/* -- relbar ---------------------------------------------------------------- */
|
||||
|
||||
div.related {
|
||||
width: 100%;
|
||||
font-size: 90%;
|
||||
}
|
||||
|
||||
div.related h3 {
|
||||
display: none;
|
||||
}
|
||||
|
||||
div.related ul {
|
||||
margin: 0;
|
||||
padding: 0 0 0 10px;
|
||||
list-style: none;
|
||||
}
|
||||
|
||||
div.related li {
|
||||
display: inline;
|
||||
}
|
||||
|
||||
div.related li.right {
|
||||
float: right;
|
||||
margin-right: 5px;
|
||||
}
|
||||
|
||||
/* -- sidebar --------------------------------------------------------------- */
|
||||
|
||||
div.sphinxsidebarwrapper {
|
||||
padding: 10px 5px 0 10px;
|
||||
}
|
||||
|
||||
div.sphinxsidebar {
|
||||
float: left;
|
||||
width: 230px;
|
||||
margin-left: -100%;
|
||||
font-size: 90%;
|
||||
}
|
||||
|
||||
div.sphinxsidebar ul {
|
||||
list-style: none;
|
||||
}
|
||||
|
||||
div.sphinxsidebar ul ul,
|
||||
div.sphinxsidebar ul.want-points {
|
||||
margin-left: 20px;
|
||||
list-style: square;
|
||||
}
|
||||
|
||||
div.sphinxsidebar ul ul {
|
||||
margin-top: 0;
|
||||
margin-bottom: 0;
|
||||
}
|
||||
|
||||
div.sphinxsidebar form {
|
||||
margin-top: 10px;
|
||||
}
|
||||
|
||||
div.sphinxsidebar input {
|
||||
border: 1px solid #98dbcc;
|
||||
font-family: sans-serif;
|
||||
font-size: 1em;
|
||||
}
|
||||
|
||||
div.sphinxsidebar #searchbox input[type="text"] {
|
||||
width: 170px;
|
||||
}
|
||||
|
||||
div.sphinxsidebar #searchbox input[type="submit"] {
|
||||
width: 30px;
|
||||
}
|
||||
|
||||
img {
|
||||
border: 0;
|
||||
}
|
||||
|
||||
/* -- search page ----------------------------------------------------------- */
|
||||
|
||||
ul.search {
|
||||
margin: 10px 0 0 20px;
|
||||
padding: 0;
|
||||
}
|
||||
|
||||
ul.search li {
|
||||
padding: 5px 0 5px 20px;
|
||||
background-image: url(file.png);
|
||||
background-repeat: no-repeat;
|
||||
background-position: 0 7px;
|
||||
}
|
||||
|
||||
ul.search li a {
|
||||
font-weight: bold;
|
||||
}
|
||||
|
||||
ul.search li div.context {
|
||||
color: #888;
|
||||
margin: 2px 0 0 30px;
|
||||
text-align: left;
|
||||
}
|
||||
|
||||
ul.keywordmatches li.goodmatch a {
|
||||
font-weight: bold;
|
||||
}
|
||||
|
||||
/* -- index page ------------------------------------------------------------ */
|
||||
|
||||
table.contentstable {
|
||||
width: 90%;
|
||||
}
|
||||
|
||||
table.contentstable p.biglink {
|
||||
line-height: 150%;
|
||||
}
|
||||
|
||||
a.biglink {
|
||||
font-size: 1.3em;
|
||||
}
|
||||
|
||||
span.linkdescr {
|
||||
font-style: italic;
|
||||
padding-top: 5px;
|
||||
font-size: 90%;
|
||||
}
|
||||
|
||||
/* -- general index --------------------------------------------------------- */
|
||||
|
||||
table.indextable {
|
||||
width: 100%;
|
||||
}
|
||||
|
||||
table.indextable td {
|
||||
text-align: left;
|
||||
vertical-align: top;
|
||||
}
|
||||
|
||||
table.indextable dl, table.indextable dd {
|
||||
margin-top: 0;
|
||||
margin-bottom: 0;
|
||||
}
|
||||
|
||||
table.indextable tr.pcap {
|
||||
height: 10px;
|
||||
}
|
||||
|
||||
table.indextable tr.cap {
|
||||
margin-top: 10px;
|
||||
background-color: #f2f2f2;
|
||||
}
|
||||
|
||||
img.toggler {
|
||||
margin-right: 3px;
|
||||
margin-top: 3px;
|
||||
cursor: pointer;
|
||||
}
|
||||
|
||||
div.modindex-jumpbox {
|
||||
border-top: 1px solid #ddd;
|
||||
border-bottom: 1px solid #ddd;
|
||||
margin: 1em 0 1em 0;
|
||||
padding: 0.4em;
|
||||
}
|
||||
|
||||
div.genindex-jumpbox {
|
||||
border-top: 1px solid #ddd;
|
||||
border-bottom: 1px solid #ddd;
|
||||
margin: 1em 0 1em 0;
|
||||
padding: 0.4em;
|
||||
}
|
||||
|
||||
/* -- general body styles --------------------------------------------------- */
|
||||
|
||||
a.headerlink {
|
||||
visibility: hidden;
|
||||
}
|
||||
|
||||
h1:hover > a.headerlink,
|
||||
h2:hover > a.headerlink,
|
||||
h3:hover > a.headerlink,
|
||||
h4:hover > a.headerlink,
|
||||
h5:hover > a.headerlink,
|
||||
h6:hover > a.headerlink,
|
||||
dt:hover > a.headerlink {
|
||||
visibility: visible;
|
||||
}
|
||||
|
||||
div.body p.caption {
|
||||
text-align: inherit;
|
||||
}
|
||||
|
||||
div.body td {
|
||||
text-align: left;
|
||||
}
|
||||
|
||||
.field-list ul {
|
||||
padding-left: 1em;
|
||||
}
|
||||
|
||||
.first {
|
||||
margin-top: 0 !important;
|
||||
}
|
||||
|
||||
p.rubric {
|
||||
margin-top: 30px;
|
||||
font-weight: bold;
|
||||
}
|
||||
|
||||
img.align-left, .figure.align-left, object.align-left {
|
||||
clear: left;
|
||||
float: left;
|
||||
margin-right: 1em;
|
||||
}
|
||||
|
||||
img.align-right, .figure.align-right, object.align-right {
|
||||
clear: right;
|
||||
float: right;
|
||||
margin-left: 1em;
|
||||
}
|
||||
|
||||
img.align-center, .figure.align-center, object.align-center {
|
||||
display: block;
|
||||
margin-left: auto;
|
||||
margin-right: auto;
|
||||
}
|
||||
|
||||
.align-left {
|
||||
text-align: left;
|
||||
}
|
||||
|
||||
.align-center {
|
||||
text-align: center;
|
||||
}
|
||||
|
||||
.align-right {
|
||||
text-align: right;
|
||||
}
|
||||
|
||||
/* -- sidebars -------------------------------------------------------------- */
|
||||
|
||||
div.sidebar {
|
||||
margin: 0 0 0.5em 1em;
|
||||
border: 1px solid #ddb;
|
||||
padding: 7px 7px 0 7px;
|
||||
background-color: #ffe;
|
||||
width: 40%;
|
||||
float: right;
|
||||
}
|
||||
|
||||
p.sidebar-title {
|
||||
font-weight: bold;
|
||||
}
|
||||
|
||||
/* -- topics ---------------------------------------------------------------- */
|
||||
|
||||
div.topic {
|
||||
border: 1px solid #ccc;
|
||||
padding: 7px 7px 0 7px;
|
||||
margin: 10px 0 10px 0;
|
||||
}
|
||||
|
||||
p.topic-title {
|
||||
font-size: 1.1em;
|
||||
font-weight: bold;
|
||||
margin-top: 10px;
|
||||
}
|
||||
|
||||
/* -- admonitions ----------------------------------------------------------- */
|
||||
|
||||
div.admonition {
|
||||
margin-top: 10px;
|
||||
margin-bottom: 10px;
|
||||
padding: 7px;
|
||||
}
|
||||
|
||||
div.admonition dt {
|
||||
font-weight: bold;
|
||||
}
|
||||
|
||||
div.admonition dl {
|
||||
margin-bottom: 0;
|
||||
}
|
||||
|
||||
p.admonition-title {
|
||||
margin: 0px 10px 5px 0px;
|
||||
font-weight: bold;
|
||||
}
|
||||
|
||||
div.body p.centered {
|
||||
text-align: center;
|
||||
margin-top: 25px;
|
||||
}
|
||||
|
||||
/* -- tables ---------------------------------------------------------------- */
|
||||
|
||||
table.docutils {
|
||||
border: 0;
|
||||
border-collapse: collapse;
|
||||
}
|
||||
|
||||
table.docutils td, table.docutils th {
|
||||
padding: 1px 8px 1px 5px;
|
||||
border-top: 0;
|
||||
border-left: 0;
|
||||
border-right: 0;
|
||||
border-bottom: 1px solid #aaa;
|
||||
}
|
||||
|
||||
table.field-list td, table.field-list th {
|
||||
border: 0 !important;
|
||||
}
|
||||
|
||||
table.footnote td, table.footnote th {
|
||||
border: 0 !important;
|
||||
}
|
||||
|
||||
th {
|
||||
text-align: left;
|
||||
padding-right: 5px;
|
||||
}
|
||||
|
||||
table.citation {
|
||||
border-left: solid 1px gray;
|
||||
margin-left: 1px;
|
||||
}
|
||||
|
||||
table.citation td {
|
||||
border-bottom: none;
|
||||
}
|
||||
|
||||
/* -- other body styles ----------------------------------------------------- */
|
||||
|
||||
ol.arabic {
|
||||
list-style: decimal;
|
||||
}
|
||||
|
||||
ol.loweralpha {
|
||||
list-style: lower-alpha;
|
||||
}
|
||||
|
||||
ol.upperalpha {
|
||||
list-style: upper-alpha;
|
||||
}
|
||||
|
||||
ol.lowerroman {
|
||||
list-style: lower-roman;
|
||||
}
|
||||
|
||||
ol.upperroman {
|
||||
list-style: upper-roman;
|
||||
}
|
||||
|
||||
dl {
|
||||
margin-bottom: 15px;
|
||||
}
|
||||
|
||||
dd p {
|
||||
margin-top: 0px;
|
||||
}
|
||||
|
||||
dd ul, dd table {
|
||||
margin-bottom: 10px;
|
||||
}
|
||||
|
||||
dd {
|
||||
margin-top: 3px;
|
||||
margin-bottom: 10px;
|
||||
margin-left: 30px;
|
||||
}
|
||||
|
||||
dt:target, .highlighted {
|
||||
background-color: #fbe54e;
|
||||
}
|
||||
|
||||
dl.glossary dt {
|
||||
font-weight: bold;
|
||||
font-size: 1.1em;
|
||||
}
|
||||
|
||||
.field-list ul {
|
||||
margin: 0;
|
||||
padding-left: 1em;
|
||||
}
|
||||
|
||||
.field-list p {
|
||||
margin: 0;
|
||||
}
|
||||
|
||||
.refcount {
|
||||
color: #060;
|
||||
}
|
||||
|
||||
.optional {
|
||||
font-size: 1.3em;
|
||||
}
|
||||
|
||||
.versionmodified {
|
||||
font-style: italic;
|
||||
}
|
||||
|
||||
.system-message {
|
||||
background-color: #fda;
|
||||
padding: 5px;
|
||||
border: 3px solid red;
|
||||
}
|
||||
|
||||
.footnote:target {
|
||||
background-color: #ffa;
|
||||
}
|
||||
|
||||
.line-block {
|
||||
display: block;
|
||||
margin-top: 1em;
|
||||
margin-bottom: 1em;
|
||||
}
|
||||
|
||||
.line-block .line-block {
|
||||
margin-top: 0;
|
||||
margin-bottom: 0;
|
||||
margin-left: 1.5em;
|
||||
}
|
||||
|
||||
.guilabel, .menuselection {
|
||||
font-family: sans-serif;
|
||||
}
|
||||
|
||||
.accelerator {
|
||||
text-decoration: underline;
|
||||
}
|
||||
|
||||
.classifier {
|
||||
font-style: oblique;
|
||||
}
|
||||
|
||||
abbr, acronym {
|
||||
border-bottom: dotted 1px;
|
||||
cursor: help;
|
||||
}
|
||||
|
||||
/* -- code displays --------------------------------------------------------- */
|
||||
|
||||
pre {
|
||||
overflow: auto;
|
||||
overflow-y: hidden; /* fixes display issues on Chrome browsers */
|
||||
}
|
||||
|
||||
td.linenos pre {
|
||||
padding: 5px 0px;
|
||||
border: 0;
|
||||
background-color: transparent;
|
||||
color: #aaa;
|
||||
}
|
||||
|
||||
table.highlighttable {
|
||||
margin-left: 0.5em;
|
||||
}
|
||||
|
||||
table.highlighttable td {
|
||||
padding: 0 0.5em 0 0.5em;
|
||||
}
|
||||
|
||||
tt.descname {
|
||||
background-color: transparent;
|
||||
font-weight: bold;
|
||||
font-size: 1.2em;
|
||||
}
|
||||
|
||||
tt.descclassname {
|
||||
background-color: transparent;
|
||||
}
|
||||
|
||||
tt.xref, a tt {
|
||||
background-color: transparent;
|
||||
font-weight: bold;
|
||||
}
|
||||
|
||||
h1 tt, h2 tt, h3 tt, h4 tt, h5 tt, h6 tt {
|
||||
background-color: transparent;
|
||||
}
|
||||
|
||||
.viewcode-link {
|
||||
float: right;
|
||||
}
|
||||
|
||||
.viewcode-back {
|
||||
float: right;
|
||||
font-family: sans-serif;
|
||||
}
|
||||
|
||||
div.viewcode-block:target {
|
||||
margin: -1px -10px;
|
||||
padding: 0 10px;
|
||||
}
|
||||
|
||||
/* -- math display ---------------------------------------------------------- */
|
||||
|
||||
img.math {
|
||||
vertical-align: middle;
|
||||
}
|
||||
|
||||
div.body div.math p {
|
||||
text-align: center;
|
||||
}
|
||||
|
||||
span.eqno {
|
||||
float: right;
|
||||
}
|
||||
|
||||
/* -- printout stylesheet --------------------------------------------------- */
|
||||
|
||||
@media print {
|
||||
div.document,
|
||||
div.documentwrapper,
|
||||
div.bodywrapper {
|
||||
margin: 0 !important;
|
||||
width: 100%;
|
||||
}
|
||||
|
||||
div.sphinxsidebar,
|
||||
div.related,
|
||||
div.footer,
|
||||
#top-link {
|
||||
display: none;
|
||||
}
|
||||
}
|
||||
@ -0,0 +1,55 @@
|
||||
/* ============================================================
|
||||
* bootstrap-dropdown.js v1.4.0
|
||||
* http://twitter.github.com/bootstrap/javascript.html#dropdown
|
||||
* ============================================================
|
||||
* Copyright 2011 Twitter, Inc.
|
||||
*
|
||||
* Licensed under the Apache License, Version 2.0 (the "License");
|
||||
* you may not use this file except in compliance with the License.
|
||||
* You may obtain a copy of the License at
|
||||
*
|
||||
* http://www.apache.org/licenses/LICENSE-2.0
|
||||
*
|
||||
* Unless required by applicable law or agreed to in writing, software
|
||||
* distributed under the License is distributed on an "AS IS" BASIS,
|
||||
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||
* See the License for the specific language governing permissions and
|
||||
* limitations under the License.
|
||||
* ============================================================ */
|
||||
|
||||
|
||||
!function( $ ){
|
||||
|
||||
"use strict"
|
||||
|
||||
/* DROPDOWN PLUGIN DEFINITION
|
||||
* ========================== */
|
||||
|
||||
$.fn.dropdown = function ( selector ) {
|
||||
return this.each(function () {
|
||||
$(this).delegate(selector || d, 'click', function (e) {
|
||||
var li = $(this).parent('li')
|
||||
, isActive = li.hasClass('open')
|
||||
|
||||
clearMenus()
|
||||
!isActive && li.toggleClass('open')
|
||||
return false
|
||||
})
|
||||
})
|
||||
}
|
||||
|
||||
/* APPLY TO STANDARD DROPDOWN ELEMENTS
|
||||
* =================================== */
|
||||
|
||||
var d = 'a.menu, .dropdown-toggle'
|
||||
|
||||
function clearMenus() {
|
||||
$(d).parent('li').removeClass('open')
|
||||
}
|
||||
|
||||
$(function () {
|
||||
$('html').bind("click", clearMenus)
|
||||
$('body').dropdown( '[data-dropdown] a.menu, [data-dropdown] .dropdown-toggle' )
|
||||
})
|
||||
|
||||
}( window.jQuery || window.ender );
|
||||
@ -0,0 +1,107 @@
|
||||
/* =============================================================
|
||||
* bootstrap-scrollspy.js v1.4.0
|
||||
* http://twitter.github.com/bootstrap/javascript.html#scrollspy
|
||||
* =============================================================
|
||||
* Copyright 2011 Twitter, Inc.
|
||||
*
|
||||
* Licensed under the Apache License, Version 2.0 (the "License");
|
||||
* you may not use this file except in compliance with the License.
|
||||
* You may obtain a copy of the License at
|
||||
*
|
||||
* http://www.apache.org/licenses/LICENSE-2.0
|
||||
*
|
||||
* Unless required by applicable law or agreed to in writing, software
|
||||
* distributed under the License is distributed on an "AS IS" BASIS,
|
||||
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||
* See the License for the specific language governing permissions and
|
||||
* limitations under the License.
|
||||
* ============================================================== */
|
||||
|
||||
|
||||
!function ( $ ) {
|
||||
|
||||
"use strict"
|
||||
|
||||
var $window = $(window)
|
||||
|
||||
function ScrollSpy( topbar, selector ) {
|
||||
var processScroll = $.proxy(this.processScroll, this)
|
||||
this.$topbar = $(topbar)
|
||||
this.selector = selector || 'li > a'
|
||||
this.refresh()
|
||||
this.$topbar.delegate(this.selector, 'click', processScroll)
|
||||
$window.scroll(processScroll)
|
||||
this.processScroll()
|
||||
}
|
||||
|
||||
ScrollSpy.prototype = {
|
||||
|
||||
refresh: function () {
|
||||
this.targets = this.$topbar.find(this.selector).map(function () {
|
||||
var href = $(this).attr('href')
|
||||
return /^#\w/.test(href) && $(href).length ? href : null
|
||||
})
|
||||
|
||||
this.offsets = $.map(this.targets, function (id) {
|
||||
return $(id).offset().top
|
||||
})
|
||||
}
|
||||
|
||||
, processScroll: function () {
|
||||
var scrollTop = $window.scrollTop() + 10
|
||||
, offsets = this.offsets
|
||||
, targets = this.targets
|
||||
, activeTarget = this.activeTarget
|
||||
, i
|
||||
|
||||
for (i = offsets.length; i--;) {
|
||||
activeTarget != targets[i]
|
||||
&& scrollTop >= offsets[i]
|
||||
&& (!offsets[i + 1] || scrollTop <= offsets[i + 1])
|
||||
&& this.activateButton( targets[i] )
|
||||
}
|
||||
}
|
||||
|
||||
, activateButton: function (target) {
|
||||
this.activeTarget = target
|
||||
|
||||
this.$topbar
|
||||
.find(this.selector).parent('.active')
|
||||
.removeClass('active')
|
||||
|
||||
this.$topbar
|
||||
.find(this.selector + '[href="' + target + '"]')
|
||||
.parent('li')
|
||||
.addClass('active')
|
||||
}
|
||||
|
||||
}
|
||||
|
||||
/* SCROLLSPY PLUGIN DEFINITION
|
||||
* =========================== */
|
||||
|
||||
$.fn.scrollSpy = function( options ) {
|
||||
var scrollspy = this.data('scrollspy')
|
||||
|
||||
if (!scrollspy) {
|
||||
return this.each(function () {
|
||||
$(this).data('scrollspy', new ScrollSpy( this, options ))
|
||||
})
|
||||
}
|
||||
|
||||
if ( options === true ) {
|
||||
return scrollspy
|
||||
}
|
||||
|
||||
if ( typeof options == 'string' ) {
|
||||
scrollspy[options]()
|
||||
}
|
||||
|
||||
return this
|
||||
}
|
||||
|
||||
$(document).ready(function () {
|
||||
$('body').scrollSpy('[data-scrollspy] li > a')
|
||||
})
|
||||
|
||||
}( window.jQuery || window.ender );
|
||||
@ -0,0 +1,15 @@
|
||||
/*
|
||||
* bootstrap-sphinx.css
|
||||
* ~~~~~~~~~~~~~~~~~~~~
|
||||
*
|
||||
* Sphinx stylesheet -- Twitter Bootstrap theme.
|
||||
*/
|
||||
|
||||
body {
|
||||
padding-top: 42px;
|
||||
}
|
||||
|
||||
div.documentwrapper {
|
||||
float: left;
|
||||
width: 100%;
|
||||
}
|
||||
File diff suppressed because it is too large
Load Diff
@ -0,0 +1,256 @@
|
||||
/*
|
||||
* default.css_t
|
||||
* ~~~~~~~~~~~~~
|
||||
*
|
||||
* Sphinx stylesheet -- default theme.
|
||||
*
|
||||
* :copyright: Copyright 2007-2011 by the Sphinx team, see AUTHORS.
|
||||
* :license: BSD, see LICENSE for details.
|
||||
*
|
||||
*/
|
||||
|
||||
@import url("basic.css");
|
||||
|
||||
/* -- page layout ----------------------------------------------------------- */
|
||||
|
||||
body {
|
||||
font-family: sans-serif;
|
||||
font-size: 100%;
|
||||
background-color: #11303d;
|
||||
color: #000;
|
||||
margin: 0;
|
||||
padding: 0;
|
||||
}
|
||||
|
||||
div.document {
|
||||
background-color: #1c4e63;
|
||||
}
|
||||
|
||||
div.documentwrapper {
|
||||
float: left;
|
||||
width: 100%;
|
||||
}
|
||||
|
||||
div.bodywrapper {
|
||||
margin: 0 0 0 230px;
|
||||
}
|
||||
|
||||
div.body {
|
||||
background-color: #ffffff;
|
||||
color: #000000;
|
||||
padding: 0 20px 30px 20px;
|
||||
}
|
||||
|
||||
div.footer {
|
||||
color: #ffffff;
|
||||
width: 100%;
|
||||
padding: 9px 0 9px 0;
|
||||
text-align: center;
|
||||
font-size: 75%;
|
||||
}
|
||||
|
||||
div.footer a {
|
||||
color: #ffffff;
|
||||
text-decoration: underline;
|
||||
}
|
||||
|
||||
div.related {
|
||||
background-color: #133f52;
|
||||
line-height: 30px;
|
||||
color: #ffffff;
|
||||
}
|
||||
|
||||
div.related a {
|
||||
color: #ffffff;
|
||||
}
|
||||
|
||||
div.sphinxsidebar {
|
||||
}
|
||||
|
||||
div.sphinxsidebar h3 {
|
||||
font-family: 'Trebuchet MS', sans-serif;
|
||||
color: #ffffff;
|
||||
font-size: 1.4em;
|
||||
font-weight: normal;
|
||||
margin: 0;
|
||||
padding: 0;
|
||||
}
|
||||
|
||||
div.sphinxsidebar h3 a {
|
||||
color: #ffffff;
|
||||
}
|
||||
|
||||
div.sphinxsidebar h4 {
|
||||
font-family: 'Trebuchet MS', sans-serif;
|
||||
color: #ffffff;
|
||||
font-size: 1.3em;
|
||||
font-weight: normal;
|
||||
margin: 5px 0 0 0;
|
||||
padding: 0;
|
||||
}
|
||||
|
||||
div.sphinxsidebar p {
|
||||
color: #ffffff;
|
||||
}
|
||||
|
||||
div.sphinxsidebar p.topless {
|
||||
margin: 5px 10px 10px 10px;
|
||||
}
|
||||
|
||||
div.sphinxsidebar ul {
|
||||
margin: 10px;
|
||||
padding: 0;
|
||||
color: #ffffff;
|
||||
}
|
||||
|
||||
div.sphinxsidebar a {
|
||||
color: #98dbcc;
|
||||
}
|
||||
|
||||
div.sphinxsidebar input {
|
||||
border: 1px solid #98dbcc;
|
||||
font-family: sans-serif;
|
||||
font-size: 1em;
|
||||
}
|
||||
|
||||
|
||||
|
||||
/* -- hyperlink styles ------------------------------------------------------ */
|
||||
|
||||
a {
|
||||
color: #355f7c;
|
||||
text-decoration: none;
|
||||
}
|
||||
|
||||
a:visited {
|
||||
color: #355f7c;
|
||||
text-decoration: none;
|
||||
}
|
||||
|
||||
a:hover {
|
||||
text-decoration: underline;
|
||||
}
|
||||
|
||||
|
||||
|
||||
/* -- body styles ----------------------------------------------------------- */
|
||||
|
||||
div.body h1,
|
||||
div.body h2,
|
||||
div.body h3,
|
||||
div.body h4,
|
||||
div.body h5,
|
||||
div.body h6 {
|
||||
font-family: 'Trebuchet MS', sans-serif;
|
||||
background-color: #f2f2f2;
|
||||
font-weight: normal;
|
||||
color: #20435c;
|
||||
border-bottom: 1px solid #ccc;
|
||||
margin: 20px -20px 10px -20px;
|
||||
padding: 3px 0 3px 10px;
|
||||
}
|
||||
|
||||
div.body h1 { margin-top: 0; font-size: 200%; }
|
||||
div.body h2 { font-size: 160%; }
|
||||
div.body h3 { font-size: 140%; }
|
||||
div.body h4 { font-size: 120%; }
|
||||
div.body h5 { font-size: 110%; }
|
||||
div.body h6 { font-size: 100%; }
|
||||
|
||||
a.headerlink {
|
||||
color: #c60f0f;
|
||||
font-size: 0.8em;
|
||||
padding: 0 4px 0 4px;
|
||||
text-decoration: none;
|
||||
}
|
||||
|
||||
a.headerlink:hover {
|
||||
background-color: #c60f0f;
|
||||
color: white;
|
||||
}
|
||||
|
||||
div.body p, div.body dd, div.body li {
|
||||
text-align: justify;
|
||||
line-height: 130%;
|
||||
}
|
||||
|
||||
div.admonition p.admonition-title + p {
|
||||
display: inline;
|
||||
}
|
||||
|
||||
div.admonition p {
|
||||
margin-bottom: 5px;
|
||||
}
|
||||
|
||||
div.admonition pre {
|
||||
margin-bottom: 5px;
|
||||
}
|
||||
|
||||
div.admonition ul, div.admonition ol {
|
||||
margin-bottom: 5px;
|
||||
}
|
||||
|
||||
div.note {
|
||||
background-color: #eee;
|
||||
border: 1px solid #ccc;
|
||||
}
|
||||
|
||||
div.seealso {
|
||||
background-color: #ffc;
|
||||
border: 1px solid #ff6;
|
||||
}
|
||||
|
||||
div.topic {
|
||||
background-color: #eee;
|
||||
}
|
||||
|
||||
div.warning {
|
||||
background-color: #ffe4e4;
|
||||
border: 1px solid #f66;
|
||||
}
|
||||
|
||||
p.admonition-title {
|
||||
display: inline;
|
||||
}
|
||||
|
||||
p.admonition-title:after {
|
||||
content: ":";
|
||||
}
|
||||
|
||||
pre {
|
||||
padding: 5px;
|
||||
background-color: #eeffcc;
|
||||
color: #333333;
|
||||
line-height: 120%;
|
||||
border: 1px solid #ac9;
|
||||
border-left: none;
|
||||
border-right: none;
|
||||
}
|
||||
|
||||
tt {
|
||||
background-color: #ecf0f3;
|
||||
padding: 0 1px 0 1px;
|
||||
font-size: 0.95em;
|
||||
}
|
||||
|
||||
th {
|
||||
background-color: #ede;
|
||||
}
|
||||
|
||||
.warning tt {
|
||||
background: #efc2c2;
|
||||
}
|
||||
|
||||
.note tt {
|
||||
background: #d6d6d6;
|
||||
}
|
||||
|
||||
.viewcode-back {
|
||||
font-family: sans-serif;
|
||||
}
|
||||
|
||||
div.viewcode-block:target {
|
||||
background-color: #f4debf;
|
||||
border-top: 1px solid #ac9;
|
||||
border-bottom: 1px solid #ac9;
|
||||
}
|
||||
@ -0,0 +1,247 @@
|
||||
/*
|
||||
* doctools.js
|
||||
* ~~~~~~~~~~~
|
||||
*
|
||||
* Sphinx JavaScript utilities for all documentation.
|
||||
*
|
||||
* :copyright: Copyright 2007-2011 by the Sphinx team, see AUTHORS.
|
||||
* :license: BSD, see LICENSE for details.
|
||||
*
|
||||
*/
|
||||
|
||||
/**
|
||||
* select a different prefix for underscore
|
||||
*/
|
||||
$u = _.noConflict();
|
||||
|
||||
/**
|
||||
* make the code below compatible with browsers without
|
||||
* an installed firebug like debugger
|
||||
if (!window.console || !console.firebug) {
|
||||
var names = ["log", "debug", "info", "warn", "error", "assert", "dir",
|
||||
"dirxml", "group", "groupEnd", "time", "timeEnd", "count", "trace",
|
||||
"profile", "profileEnd"];
|
||||
window.console = {};
|
||||
for (var i = 0; i < names.length; ++i)
|
||||
window.console[names[i]] = function() {};
|
||||
}
|
||||
*/
|
||||
|
||||
/**
|
||||
* small helper function to urldecode strings
|
||||
*/
|
||||
jQuery.urldecode = function(x) {
|
||||
return decodeURIComponent(x).replace(/\+/g, ' ');
|
||||
}
|
||||
|
||||
/**
|
||||
* small helper function to urlencode strings
|
||||
*/
|
||||
jQuery.urlencode = encodeURIComponent;
|
||||
|
||||
/**
|
||||
* This function returns the parsed url parameters of the
|
||||
* current request. Multiple values per key are supported,
|
||||
* it will always return arrays of strings for the value parts.
|
||||
*/
|
||||
jQuery.getQueryParameters = function(s) {
|
||||
if (typeof s == 'undefined')
|
||||
s = document.location.search;
|
||||
var parts = s.substr(s.indexOf('?') + 1).split('&');
|
||||
var result = {};
|
||||
for (var i = 0; i < parts.length; i++) {
|
||||
var tmp = parts[i].split('=', 2);
|
||||
var key = jQuery.urldecode(tmp[0]);
|
||||
var value = jQuery.urldecode(tmp[1]);
|
||||
if (key in result)
|
||||
result[key].push(value);
|
||||
else
|
||||
result[key] = [value];
|
||||
}
|
||||
return result;
|
||||
};
|
||||
|
||||
/**
|
||||
* small function to check if an array contains
|
||||
* a given item.
|
||||
*/
|
||||
jQuery.contains = function(arr, item) {
|
||||
for (var i = 0; i < arr.length; i++) {
|
||||
if (arr[i] == item)
|
||||
return true;
|
||||
}
|
||||
return false;
|
||||
};
|
||||
|
||||
/**
|
||||
* highlight a given string on a jquery object by wrapping it in
|
||||
* span elements with the given class name.
|
||||
*/
|
||||
jQuery.fn.highlightText = function(text, className) {
|
||||
function highlight(node) {
|
||||
if (node.nodeType == 3) {
|
||||
var val = node.nodeValue;
|
||||
var pos = val.toLowerCase().indexOf(text);
|
||||
if (pos >= 0 && !jQuery(node.parentNode).hasClass(className)) {
|
||||
var span = document.createElement("span");
|
||||
span.className = className;
|
||||
span.appendChild(document.createTextNode(val.substr(pos, text.length)));
|
||||
node.parentNode.insertBefore(span, node.parentNode.insertBefore(
|
||||
document.createTextNode(val.substr(pos + text.length)),
|
||||
node.nextSibling));
|
||||
node.nodeValue = val.substr(0, pos);
|
||||
}
|
||||
}
|
||||
else if (!jQuery(node).is("button, select, textarea")) {
|
||||
jQuery.each(node.childNodes, function() {
|
||||
highlight(this);
|
||||
});
|
||||
}
|
||||
}
|
||||
return this.each(function() {
|
||||
highlight(this);
|
||||
});
|
||||
};
|
||||
|
||||
/**
|
||||
* Small JavaScript module for the documentation.
|
||||
*/
|
||||
var Documentation = {
|
||||
|
||||
init : function() {
|
||||
this.fixFirefoxAnchorBug();
|
||||
this.highlightSearchWords();
|
||||
this.initIndexTable();
|
||||
},
|
||||
|
||||
/**
|
||||
* i18n support
|
||||
*/
|
||||
TRANSLATIONS : {},
|
||||
PLURAL_EXPR : function(n) { return n == 1 ? 0 : 1; },
|
||||
LOCALE : 'unknown',
|
||||
|
||||
// gettext and ngettext don't access this so that the functions
|
||||
// can safely bound to a different name (_ = Documentation.gettext)
|
||||
gettext : function(string) {
|
||||
var translated = Documentation.TRANSLATIONS[string];
|
||||
if (typeof translated == 'undefined')
|
||||
return string;
|
||||
return (typeof translated == 'string') ? translated : translated[0];
|
||||
},
|
||||
|
||||
ngettext : function(singular, plural, n) {
|
||||
var translated = Documentation.TRANSLATIONS[singular];
|
||||
if (typeof translated == 'undefined')
|
||||
return (n == 1) ? singular : plural;
|
||||
return translated[Documentation.PLURALEXPR(n)];
|
||||
},
|
||||
|
||||
addTranslations : function(catalog) {
|
||||
for (var key in catalog.messages)
|
||||
this.TRANSLATIONS[key] = catalog.messages[key];
|
||||
this.PLURAL_EXPR = new Function('n', 'return +(' + catalog.plural_expr + ')');
|
||||
this.LOCALE = catalog.locale;
|
||||
},
|
||||
|
||||
/**
|
||||
* add context elements like header anchor links
|
||||
*/
|
||||
addContextElements : function() {
|
||||
$('div[id] > :header:first').each(function() {
|
||||
$('<a class="headerlink">\u00B6</a>').
|
||||
attr('href', '#' + this.id).
|
||||
attr('title', _('Permalink to this headline')).
|
||||
appendTo(this);
|
||||
});
|
||||
$('dt[id]').each(function() {
|
||||
$('<a class="headerlink">\u00B6</a>').
|
||||
attr('href', '#' + this.id).
|
||||
attr('title', _('Permalink to this definition')).
|
||||
appendTo(this);
|
||||
});
|
||||
},
|
||||
|
||||
/**
|
||||
* workaround a firefox stupidity
|
||||
*/
|
||||
fixFirefoxAnchorBug : function() {
|
||||
if (document.location.hash && $.browser.mozilla)
|
||||
window.setTimeout(function() {
|
||||
document.location.href += '';
|
||||
}, 10);
|
||||
},
|
||||
|
||||
/**
|
||||
* highlight the search words provided in the url in the text
|
||||
*/
|
||||
highlightSearchWords : function() {
|
||||
var params = $.getQueryParameters();
|
||||
var terms = (params.highlight) ? params.highlight[0].split(/\s+/) : [];
|
||||
if (terms.length) {
|
||||
var body = $('div.body');
|
||||
window.setTimeout(function() {
|
||||
$.each(terms, function() {
|
||||
body.highlightText(this.toLowerCase(), 'highlighted');
|
||||
});
|
||||
}, 10);
|
||||
$('<p class="highlight-link"><a href="javascript:Documentation.' +
|
||||
'hideSearchWords()">' + _('Hide Search Matches') + '</a></p>')
|
||||
.appendTo($('#searchbox'));
|
||||
}
|
||||
},
|
||||
|
||||
/**
|
||||
* init the domain index toggle buttons
|
||||
*/
|
||||
initIndexTable : function() {
|
||||
var togglers = $('img.toggler').click(function() {
|
||||
var src = $(this).attr('src');
|
||||
var idnum = $(this).attr('id').substr(7);
|
||||
$('tr.cg-' + idnum).toggle();
|
||||
if (src.substr(-9) == 'minus.png')
|
||||
$(this).attr('src', src.substr(0, src.length-9) + 'plus.png');
|
||||
else
|
||||
$(this).attr('src', src.substr(0, src.length-8) + 'minus.png');
|
||||
}).css('display', '');
|
||||
if (DOCUMENTATION_OPTIONS.COLLAPSE_INDEX) {
|
||||
togglers.click();
|
||||
}
|
||||
},
|
||||
|
||||
/**
|
||||
* helper function to hide the search marks again
|
||||
*/
|
||||
hideSearchWords : function() {
|
||||
$('#searchbox .highlight-link').fadeOut(300);
|
||||
$('span.highlighted').removeClass('highlighted');
|
||||
},
|
||||
|
||||
/**
|
||||
* make the url absolute
|
||||
*/
|
||||
makeURL : function(relativeURL) {
|
||||
return DOCUMENTATION_OPTIONS.URL_ROOT + '/' + relativeURL;
|
||||
},
|
||||
|
||||
/**
|
||||
* get the current relative url
|
||||
*/
|
||||
getCurrentURL : function() {
|
||||
var path = document.location.pathname;
|
||||
var parts = path.split(/\//);
|
||||
$.each(DOCUMENTATION_OPTIONS.URL_ROOT.split(/\//), function() {
|
||||
if (this == '..')
|
||||
parts.pop();
|
||||
});
|
||||
var url = parts.join('/');
|
||||
return path.substring(url.lastIndexOf('/') + 1, path.length - 1);
|
||||
}
|
||||
};
|
||||
|
||||
// quick alias for translations
|
||||
_ = Documentation.gettext;
|
||||
|
||||
$(document).ready(function() {
|
||||
Documentation.init();
|
||||
});
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 318 B |
Binary file not shown.
|
After Width: | Height: | Size: 392 B |
@ -0,0 +1,154 @@
|
||||
/*!
|
||||
* jQuery JavaScript Library v1.4.2
|
||||
* http://jquery.com/
|
||||
*
|
||||
* Copyright 2010, John Resig
|
||||
* Dual licensed under the MIT or GPL Version 2 licenses.
|
||||
* http://jquery.org/license
|
||||
*
|
||||
* Includes Sizzle.js
|
||||
* http://sizzlejs.com/
|
||||
* Copyright 2010, The Dojo Foundation
|
||||
* Released under the MIT, BSD, and GPL Licenses.
|
||||
*
|
||||
* Date: Sat Feb 13 22:33:48 2010 -0500
|
||||
*/
|
||||
(function(A,w){function ma(){if(!c.isReady){try{s.documentElement.doScroll("left")}catch(a){setTimeout(ma,1);return}c.ready()}}function Qa(a,b){b.src?c.ajax({url:b.src,async:false,dataType:"script"}):c.globalEval(b.text||b.textContent||b.innerHTML||"");b.parentNode&&b.parentNode.removeChild(b)}function X(a,b,d,f,e,j){var i=a.length;if(typeof b==="object"){for(var o in b)X(a,o,b[o],f,e,d);return a}if(d!==w){f=!j&&f&&c.isFunction(d);for(o=0;o<i;o++)e(a[o],b,f?d.call(a[o],o,e(a[o],b)):d,j);return a}return i?
|
||||
e(a[0],b):w}function J(){return(new Date).getTime()}function Y(){return false}function Z(){return true}function na(a,b,d){d[0].type=a;return c.event.handle.apply(b,d)}function oa(a){var b,d=[],f=[],e=arguments,j,i,o,k,n,r;i=c.data(this,"events");if(!(a.liveFired===this||!i||!i.live||a.button&&a.type==="click")){a.liveFired=this;var u=i.live.slice(0);for(k=0;k<u.length;k++){i=u[k];i.origType.replace(O,"")===a.type?f.push(i.selector):u.splice(k--,1)}j=c(a.target).closest(f,a.currentTarget);n=0;for(r=
|
||||
j.length;n<r;n++)for(k=0;k<u.length;k++){i=u[k];if(j[n].selector===i.selector){o=j[n].elem;f=null;if(i.preType==="mouseenter"||i.preType==="mouseleave")f=c(a.relatedTarget).closest(i.selector)[0];if(!f||f!==o)d.push({elem:o,handleObj:i})}}n=0;for(r=d.length;n<r;n++){j=d[n];a.currentTarget=j.elem;a.data=j.handleObj.data;a.handleObj=j.handleObj;if(j.handleObj.origHandler.apply(j.elem,e)===false){b=false;break}}return b}}function pa(a,b){return"live."+(a&&a!=="*"?a+".":"")+b.replace(/\./g,"`").replace(/ /g,
|
||||
"&")}function qa(a){return!a||!a.parentNode||a.parentNode.nodeType===11}function ra(a,b){var d=0;b.each(function(){if(this.nodeName===(a[d]&&a[d].nodeName)){var f=c.data(a[d++]),e=c.data(this,f);if(f=f&&f.events){delete e.handle;e.events={};for(var j in f)for(var i in f[j])c.event.add(this,j,f[j][i],f[j][i].data)}}})}function sa(a,b,d){var f,e,j;b=b&&b[0]?b[0].ownerDocument||b[0]:s;if(a.length===1&&typeof a[0]==="string"&&a[0].length<512&&b===s&&!ta.test(a[0])&&(c.support.checkClone||!ua.test(a[0]))){e=
|
||||
true;if(j=c.fragments[a[0]])if(j!==1)f=j}if(!f){f=b.createDocumentFragment();c.clean(a,b,f,d)}if(e)c.fragments[a[0]]=j?f:1;return{fragment:f,cacheable:e}}function K(a,b){var d={};c.each(va.concat.apply([],va.slice(0,b)),function(){d[this]=a});return d}function wa(a){return"scrollTo"in a&&a.document?a:a.nodeType===9?a.defaultView||a.parentWindow:false}var c=function(a,b){return new c.fn.init(a,b)},Ra=A.jQuery,Sa=A.$,s=A.document,T,Ta=/^[^<]*(<[\w\W]+>)[^>]*$|^#([\w-]+)$/,Ua=/^.[^:#\[\.,]*$/,Va=/\S/,
|
||||
Wa=/^(\s|\u00A0)+|(\s|\u00A0)+$/g,Xa=/^<(\w+)\s*\/?>(?:<\/\1>)?$/,P=navigator.userAgent,xa=false,Q=[],L,$=Object.prototype.toString,aa=Object.prototype.hasOwnProperty,ba=Array.prototype.push,R=Array.prototype.slice,ya=Array.prototype.indexOf;c.fn=c.prototype={init:function(a,b){var d,f;if(!a)return this;if(a.nodeType){this.context=this[0]=a;this.length=1;return this}if(a==="body"&&!b){this.context=s;this[0]=s.body;this.selector="body";this.length=1;return this}if(typeof a==="string")if((d=Ta.exec(a))&&
|
||||
(d[1]||!b))if(d[1]){f=b?b.ownerDocument||b:s;if(a=Xa.exec(a))if(c.isPlainObject(b)){a=[s.createElement(a[1])];c.fn.attr.call(a,b,true)}else a=[f.createElement(a[1])];else{a=sa([d[1]],[f]);a=(a.cacheable?a.fragment.cloneNode(true):a.fragment).childNodes}return c.merge(this,a)}else{if(b=s.getElementById(d[2])){if(b.id!==d[2])return T.find(a);this.length=1;this[0]=b}this.context=s;this.selector=a;return this}else if(!b&&/^\w+$/.test(a)){this.selector=a;this.context=s;a=s.getElementsByTagName(a);return c.merge(this,
|
||||
a)}else return!b||b.jquery?(b||T).find(a):c(b).find(a);else if(c.isFunction(a))return T.ready(a);if(a.selector!==w){this.selector=a.selector;this.context=a.context}return c.makeArray(a,this)},selector:"",jquery:"1.4.2",length:0,size:function(){return this.length},toArray:function(){return R.call(this,0)},get:function(a){return a==null?this.toArray():a<0?this.slice(a)[0]:this[a]},pushStack:function(a,b,d){var f=c();c.isArray(a)?ba.apply(f,a):c.merge(f,a);f.prevObject=this;f.context=this.context;if(b===
|
||||
"find")f.selector=this.selector+(this.selector?" ":"")+d;else if(b)f.selector=this.selector+"."+b+"("+d+")";return f},each:function(a,b){return c.each(this,a,b)},ready:function(a){c.bindReady();if(c.isReady)a.call(s,c);else Q&&Q.push(a);return this},eq:function(a){return a===-1?this.slice(a):this.slice(a,+a+1)},first:function(){return this.eq(0)},last:function(){return this.eq(-1)},slice:function(){return this.pushStack(R.apply(this,arguments),"slice",R.call(arguments).join(","))},map:function(a){return this.pushStack(c.map(this,
|
||||
function(b,d){return a.call(b,d,b)}))},end:function(){return this.prevObject||c(null)},push:ba,sort:[].sort,splice:[].splice};c.fn.init.prototype=c.fn;c.extend=c.fn.extend=function(){var a=arguments[0]||{},b=1,d=arguments.length,f=false,e,j,i,o;if(typeof a==="boolean"){f=a;a=arguments[1]||{};b=2}if(typeof a!=="object"&&!c.isFunction(a))a={};if(d===b){a=this;--b}for(;b<d;b++)if((e=arguments[b])!=null)for(j in e){i=a[j];o=e[j];if(a!==o)if(f&&o&&(c.isPlainObject(o)||c.isArray(o))){i=i&&(c.isPlainObject(i)||
|
||||
c.isArray(i))?i:c.isArray(o)?[]:{};a[j]=c.extend(f,i,o)}else if(o!==w)a[j]=o}return a};c.extend({noConflict:function(a){A.$=Sa;if(a)A.jQuery=Ra;return c},isReady:false,ready:function(){if(!c.isReady){if(!s.body)return setTimeout(c.ready,13);c.isReady=true;if(Q){for(var a,b=0;a=Q[b++];)a.call(s,c);Q=null}c.fn.triggerHandler&&c(s).triggerHandler("ready")}},bindReady:function(){if(!xa){xa=true;if(s.readyState==="complete")return c.ready();if(s.addEventListener){s.addEventListener("DOMContentLoaded",
|
||||
L,false);A.addEventListener("load",c.ready,false)}else if(s.attachEvent){s.attachEvent("onreadystatechange",L);A.attachEvent("onload",c.ready);var a=false;try{a=A.frameElement==null}catch(b){}s.documentElement.doScroll&&a&&ma()}}},isFunction:function(a){return $.call(a)==="[object Function]"},isArray:function(a){return $.call(a)==="[object Array]"},isPlainObject:function(a){if(!a||$.call(a)!=="[object Object]"||a.nodeType||a.setInterval)return false;if(a.constructor&&!aa.call(a,"constructor")&&!aa.call(a.constructor.prototype,
|
||||
"isPrototypeOf"))return false;var b;for(b in a);return b===w||aa.call(a,b)},isEmptyObject:function(a){for(var b in a)return false;return true},error:function(a){throw a;},parseJSON:function(a){if(typeof a!=="string"||!a)return null;a=c.trim(a);if(/^[\],:{}\s]*$/.test(a.replace(/\\(?:["\\\/bfnrt]|u[0-9a-fA-F]{4})/g,"@").replace(/"[^"\\\n\r]*"|true|false|null|-?\d+(?:\.\d*)?(?:[eE][+\-]?\d+)?/g,"]").replace(/(?:^|:|,)(?:\s*\[)+/g,"")))return A.JSON&&A.JSON.parse?A.JSON.parse(a):(new Function("return "+
|
||||
a))();else c.error("Invalid JSON: "+a)},noop:function(){},globalEval:function(a){if(a&&Va.test(a)){var b=s.getElementsByTagName("head")[0]||s.documentElement,d=s.createElement("script");d.type="text/javascript";if(c.support.scriptEval)d.appendChild(s.createTextNode(a));else d.text=a;b.insertBefore(d,b.firstChild);b.removeChild(d)}},nodeName:function(a,b){return a.nodeName&&a.nodeName.toUpperCase()===b.toUpperCase()},each:function(a,b,d){var f,e=0,j=a.length,i=j===w||c.isFunction(a);if(d)if(i)for(f in a){if(b.apply(a[f],
|
||||
d)===false)break}else for(;e<j;){if(b.apply(a[e++],d)===false)break}else if(i)for(f in a){if(b.call(a[f],f,a[f])===false)break}else for(d=a[0];e<j&&b.call(d,e,d)!==false;d=a[++e]);return a},trim:function(a){return(a||"").replace(Wa,"")},makeArray:function(a,b){b=b||[];if(a!=null)a.length==null||typeof a==="string"||c.isFunction(a)||typeof a!=="function"&&a.setInterval?ba.call(b,a):c.merge(b,a);return b},inArray:function(a,b){if(b.indexOf)return b.indexOf(a);for(var d=0,f=b.length;d<f;d++)if(b[d]===
|
||||
a)return d;return-1},merge:function(a,b){var d=a.length,f=0;if(typeof b.length==="number")for(var e=b.length;f<e;f++)a[d++]=b[f];else for(;b[f]!==w;)a[d++]=b[f++];a.length=d;return a},grep:function(a,b,d){for(var f=[],e=0,j=a.length;e<j;e++)!d!==!b(a[e],e)&&f.push(a[e]);return f},map:function(a,b,d){for(var f=[],e,j=0,i=a.length;j<i;j++){e=b(a[j],j,d);if(e!=null)f[f.length]=e}return f.concat.apply([],f)},guid:1,proxy:function(a,b,d){if(arguments.length===2)if(typeof b==="string"){d=a;a=d[b];b=w}else if(b&&
|
||||
!c.isFunction(b)){d=b;b=w}if(!b&&a)b=function(){return a.apply(d||this,arguments)};if(a)b.guid=a.guid=a.guid||b.guid||c.guid++;return b},uaMatch:function(a){a=a.toLowerCase();a=/(webkit)[ \/]([\w.]+)/.exec(a)||/(opera)(?:.*version)?[ \/]([\w.]+)/.exec(a)||/(msie) ([\w.]+)/.exec(a)||!/compatible/.test(a)&&/(mozilla)(?:.*? rv:([\w.]+))?/.exec(a)||[];return{browser:a[1]||"",version:a[2]||"0"}},browser:{}});P=c.uaMatch(P);if(P.browser){c.browser[P.browser]=true;c.browser.version=P.version}if(c.browser.webkit)c.browser.safari=
|
||||
true;if(ya)c.inArray=function(a,b){return ya.call(b,a)};T=c(s);if(s.addEventListener)L=function(){s.removeEventListener("DOMContentLoaded",L,false);c.ready()};else if(s.attachEvent)L=function(){if(s.readyState==="complete"){s.detachEvent("onreadystatechange",L);c.ready()}};(function(){c.support={};var a=s.documentElement,b=s.createElement("script"),d=s.createElement("div"),f="script"+J();d.style.display="none";d.innerHTML=" <link/><table></table><a href='/a' style='color:red;float:left;opacity:.55;'>a</a><input type='checkbox'/>";
|
||||
var e=d.getElementsByTagName("*"),j=d.getElementsByTagName("a")[0];if(!(!e||!e.length||!j)){c.support={leadingWhitespace:d.firstChild.nodeType===3,tbody:!d.getElementsByTagName("tbody").length,htmlSerialize:!!d.getElementsByTagName("link").length,style:/red/.test(j.getAttribute("style")),hrefNormalized:j.getAttribute("href")==="/a",opacity:/^0.55$/.test(j.style.opacity),cssFloat:!!j.style.cssFloat,checkOn:d.getElementsByTagName("input")[0].value==="on",optSelected:s.createElement("select").appendChild(s.createElement("option")).selected,
|
||||
parentNode:d.removeChild(d.appendChild(s.createElement("div"))).parentNode===null,deleteExpando:true,checkClone:false,scriptEval:false,noCloneEvent:true,boxModel:null};b.type="text/javascript";try{b.appendChild(s.createTextNode("window."+f+"=1;"))}catch(i){}a.insertBefore(b,a.firstChild);if(A[f]){c.support.scriptEval=true;delete A[f]}try{delete b.test}catch(o){c.support.deleteExpando=false}a.removeChild(b);if(d.attachEvent&&d.fireEvent){d.attachEvent("onclick",function k(){c.support.noCloneEvent=
|
||||
false;d.detachEvent("onclick",k)});d.cloneNode(true).fireEvent("onclick")}d=s.createElement("div");d.innerHTML="<input type='radio' name='radiotest' checked='checked'/>";a=s.createDocumentFragment();a.appendChild(d.firstChild);c.support.checkClone=a.cloneNode(true).cloneNode(true).lastChild.checked;c(function(){var k=s.createElement("div");k.style.width=k.style.paddingLeft="1px";s.body.appendChild(k);c.boxModel=c.support.boxModel=k.offsetWidth===2;s.body.removeChild(k).style.display="none"});a=function(k){var n=
|
||||
s.createElement("div");k="on"+k;var r=k in n;if(!r){n.setAttribute(k,"return;");r=typeof n[k]==="function"}return r};c.support.submitBubbles=a("submit");c.support.changeBubbles=a("change");a=b=d=e=j=null}})();c.props={"for":"htmlFor","class":"className",readonly:"readOnly",maxlength:"maxLength",cellspacing:"cellSpacing",rowspan:"rowSpan",colspan:"colSpan",tabindex:"tabIndex",usemap:"useMap",frameborder:"frameBorder"};var G="jQuery"+J(),Ya=0,za={};c.extend({cache:{},expando:G,noData:{embed:true,object:true,
|
||||
applet:true},data:function(a,b,d){if(!(a.nodeName&&c.noData[a.nodeName.toLowerCase()])){a=a==A?za:a;var f=a[G],e=c.cache;if(!f&&typeof b==="string"&&d===w)return null;f||(f=++Ya);if(typeof b==="object"){a[G]=f;e[f]=c.extend(true,{},b)}else if(!e[f]){a[G]=f;e[f]={}}a=e[f];if(d!==w)a[b]=d;return typeof b==="string"?a[b]:a}},removeData:function(a,b){if(!(a.nodeName&&c.noData[a.nodeName.toLowerCase()])){a=a==A?za:a;var d=a[G],f=c.cache,e=f[d];if(b){if(e){delete e[b];c.isEmptyObject(e)&&c.removeData(a)}}else{if(c.support.deleteExpando)delete a[c.expando];
|
||||
else a.removeAttribute&&a.removeAttribute(c.expando);delete f[d]}}}});c.fn.extend({data:function(a,b){if(typeof a==="undefined"&&this.length)return c.data(this[0]);else if(typeof a==="object")return this.each(function(){c.data(this,a)});var d=a.split(".");d[1]=d[1]?"."+d[1]:"";if(b===w){var f=this.triggerHandler("getData"+d[1]+"!",[d[0]]);if(f===w&&this.length)f=c.data(this[0],a);return f===w&&d[1]?this.data(d[0]):f}else return this.trigger("setData"+d[1]+"!",[d[0],b]).each(function(){c.data(this,
|
||||
a,b)})},removeData:function(a){return this.each(function(){c.removeData(this,a)})}});c.extend({queue:function(a,b,d){if(a){b=(b||"fx")+"queue";var f=c.data(a,b);if(!d)return f||[];if(!f||c.isArray(d))f=c.data(a,b,c.makeArray(d));else f.push(d);return f}},dequeue:function(a,b){b=b||"fx";var d=c.queue(a,b),f=d.shift();if(f==="inprogress")f=d.shift();if(f){b==="fx"&&d.unshift("inprogress");f.call(a,function(){c.dequeue(a,b)})}}});c.fn.extend({queue:function(a,b){if(typeof a!=="string"){b=a;a="fx"}if(b===
|
||||
w)return c.queue(this[0],a);return this.each(function(){var d=c.queue(this,a,b);a==="fx"&&d[0]!=="inprogress"&&c.dequeue(this,a)})},dequeue:function(a){return this.each(function(){c.dequeue(this,a)})},delay:function(a,b){a=c.fx?c.fx.speeds[a]||a:a;b=b||"fx";return this.queue(b,function(){var d=this;setTimeout(function(){c.dequeue(d,b)},a)})},clearQueue:function(a){return this.queue(a||"fx",[])}});var Aa=/[\n\t]/g,ca=/\s+/,Za=/\r/g,$a=/href|src|style/,ab=/(button|input)/i,bb=/(button|input|object|select|textarea)/i,
|
||||
cb=/^(a|area)$/i,Ba=/radio|checkbox/;c.fn.extend({attr:function(a,b){return X(this,a,b,true,c.attr)},removeAttr:function(a){return this.each(function(){c.attr(this,a,"");this.nodeType===1&&this.removeAttribute(a)})},addClass:function(a){if(c.isFunction(a))return this.each(function(n){var r=c(this);r.addClass(a.call(this,n,r.attr("class")))});if(a&&typeof a==="string")for(var b=(a||"").split(ca),d=0,f=this.length;d<f;d++){var e=this[d];if(e.nodeType===1)if(e.className){for(var j=" "+e.className+" ",
|
||||
i=e.className,o=0,k=b.length;o<k;o++)if(j.indexOf(" "+b[o]+" ")<0)i+=" "+b[o];e.className=c.trim(i)}else e.className=a}return this},removeClass:function(a){if(c.isFunction(a))return this.each(function(k){var n=c(this);n.removeClass(a.call(this,k,n.attr("class")))});if(a&&typeof a==="string"||a===w)for(var b=(a||"").split(ca),d=0,f=this.length;d<f;d++){var e=this[d];if(e.nodeType===1&&e.className)if(a){for(var j=(" "+e.className+" ").replace(Aa," "),i=0,o=b.length;i<o;i++)j=j.replace(" "+b[i]+" ",
|
||||
" ");e.className=c.trim(j)}else e.className=""}return this},toggleClass:function(a,b){var d=typeof a,f=typeof b==="boolean";if(c.isFunction(a))return this.each(function(e){var j=c(this);j.toggleClass(a.call(this,e,j.attr("class"),b),b)});return this.each(function(){if(d==="string")for(var e,j=0,i=c(this),o=b,k=a.split(ca);e=k[j++];){o=f?o:!i.hasClass(e);i[o?"addClass":"removeClass"](e)}else if(d==="undefined"||d==="boolean"){this.className&&c.data(this,"__className__",this.className);this.className=
|
||||
this.className||a===false?"":c.data(this,"__className__")||""}})},hasClass:function(a){a=" "+a+" ";for(var b=0,d=this.length;b<d;b++)if((" "+this[b].className+" ").replace(Aa," ").indexOf(a)>-1)return true;return false},val:function(a){if(a===w){var b=this[0];if(b){if(c.nodeName(b,"option"))return(b.attributes.value||{}).specified?b.value:b.text;if(c.nodeName(b,"select")){var d=b.selectedIndex,f=[],e=b.options;b=b.type==="select-one";if(d<0)return null;var j=b?d:0;for(d=b?d+1:e.length;j<d;j++){var i=
|
||||
e[j];if(i.selected){a=c(i).val();if(b)return a;f.push(a)}}return f}if(Ba.test(b.type)&&!c.support.checkOn)return b.getAttribute("value")===null?"on":b.value;return(b.value||"").replace(Za,"")}return w}var o=c.isFunction(a);return this.each(function(k){var n=c(this),r=a;if(this.nodeType===1){if(o)r=a.call(this,k,n.val());if(typeof r==="number")r+="";if(c.isArray(r)&&Ba.test(this.type))this.checked=c.inArray(n.val(),r)>=0;else if(c.nodeName(this,"select")){var u=c.makeArray(r);c("option",this).each(function(){this.selected=
|
||||
c.inArray(c(this).val(),u)>=0});if(!u.length)this.selectedIndex=-1}else this.value=r}})}});c.extend({attrFn:{val:true,css:true,html:true,text:true,data:true,width:true,height:true,offset:true},attr:function(a,b,d,f){if(!a||a.nodeType===3||a.nodeType===8)return w;if(f&&b in c.attrFn)return c(a)[b](d);f=a.nodeType!==1||!c.isXMLDoc(a);var e=d!==w;b=f&&c.props[b]||b;if(a.nodeType===1){var j=$a.test(b);if(b in a&&f&&!j){if(e){b==="type"&&ab.test(a.nodeName)&&a.parentNode&&c.error("type property can't be changed");
|
||||
a[b]=d}if(c.nodeName(a,"form")&&a.getAttributeNode(b))return a.getAttributeNode(b).nodeValue;if(b==="tabIndex")return(b=a.getAttributeNode("tabIndex"))&&b.specified?b.value:bb.test(a.nodeName)||cb.test(a.nodeName)&&a.href?0:w;return a[b]}if(!c.support.style&&f&&b==="style"){if(e)a.style.cssText=""+d;return a.style.cssText}e&&a.setAttribute(b,""+d);a=!c.support.hrefNormalized&&f&&j?a.getAttribute(b,2):a.getAttribute(b);return a===null?w:a}return c.style(a,b,d)}});var O=/\.(.*)$/,db=function(a){return a.replace(/[^\w\s\.\|`]/g,
|
||||
function(b){return"\\"+b})};c.event={add:function(a,b,d,f){if(!(a.nodeType===3||a.nodeType===8)){if(a.setInterval&&a!==A&&!a.frameElement)a=A;var e,j;if(d.handler){e=d;d=e.handler}if(!d.guid)d.guid=c.guid++;if(j=c.data(a)){var i=j.events=j.events||{},o=j.handle;if(!o)j.handle=o=function(){return typeof c!=="undefined"&&!c.event.triggered?c.event.handle.apply(o.elem,arguments):w};o.elem=a;b=b.split(" ");for(var k,n=0,r;k=b[n++];){j=e?c.extend({},e):{handler:d,data:f};if(k.indexOf(".")>-1){r=k.split(".");
|
||||
k=r.shift();j.namespace=r.slice(0).sort().join(".")}else{r=[];j.namespace=""}j.type=k;j.guid=d.guid;var u=i[k],z=c.event.special[k]||{};if(!u){u=i[k]=[];if(!z.setup||z.setup.call(a,f,r,o)===false)if(a.addEventListener)a.addEventListener(k,o,false);else a.attachEvent&&a.attachEvent("on"+k,o)}if(z.add){z.add.call(a,j);if(!j.handler.guid)j.handler.guid=d.guid}u.push(j);c.event.global[k]=true}a=null}}},global:{},remove:function(a,b,d,f){if(!(a.nodeType===3||a.nodeType===8)){var e,j=0,i,o,k,n,r,u,z=c.data(a),
|
||||
C=z&&z.events;if(z&&C){if(b&&b.type){d=b.handler;b=b.type}if(!b||typeof b==="string"&&b.charAt(0)==="."){b=b||"";for(e in C)c.event.remove(a,e+b)}else{for(b=b.split(" ");e=b[j++];){n=e;i=e.indexOf(".")<0;o=[];if(!i){o=e.split(".");e=o.shift();k=new RegExp("(^|\\.)"+c.map(o.slice(0).sort(),db).join("\\.(?:.*\\.)?")+"(\\.|$)")}if(r=C[e])if(d){n=c.event.special[e]||{};for(B=f||0;B<r.length;B++){u=r[B];if(d.guid===u.guid){if(i||k.test(u.namespace)){f==null&&r.splice(B--,1);n.remove&&n.remove.call(a,u)}if(f!=
|
||||
null)break}}if(r.length===0||f!=null&&r.length===1){if(!n.teardown||n.teardown.call(a,o)===false)Ca(a,e,z.handle);delete C[e]}}else for(var B=0;B<r.length;B++){u=r[B];if(i||k.test(u.namespace)){c.event.remove(a,n,u.handler,B);r.splice(B--,1)}}}if(c.isEmptyObject(C)){if(b=z.handle)b.elem=null;delete z.events;delete z.handle;c.isEmptyObject(z)&&c.removeData(a)}}}}},trigger:function(a,b,d,f){var e=a.type||a;if(!f){a=typeof a==="object"?a[G]?a:c.extend(c.Event(e),a):c.Event(e);if(e.indexOf("!")>=0){a.type=
|
||||
e=e.slice(0,-1);a.exclusive=true}if(!d){a.stopPropagation();c.event.global[e]&&c.each(c.cache,function(){this.events&&this.events[e]&&c.event.trigger(a,b,this.handle.elem)})}if(!d||d.nodeType===3||d.nodeType===8)return w;a.result=w;a.target=d;b=c.makeArray(b);b.unshift(a)}a.currentTarget=d;(f=c.data(d,"handle"))&&f.apply(d,b);f=d.parentNode||d.ownerDocument;try{if(!(d&&d.nodeName&&c.noData[d.nodeName.toLowerCase()]))if(d["on"+e]&&d["on"+e].apply(d,b)===false)a.result=false}catch(j){}if(!a.isPropagationStopped()&&
|
||||
f)c.event.trigger(a,b,f,true);else if(!a.isDefaultPrevented()){f=a.target;var i,o=c.nodeName(f,"a")&&e==="click",k=c.event.special[e]||{};if((!k._default||k._default.call(d,a)===false)&&!o&&!(f&&f.nodeName&&c.noData[f.nodeName.toLowerCase()])){try{if(f[e]){if(i=f["on"+e])f["on"+e]=null;c.event.triggered=true;f[e]()}}catch(n){}if(i)f["on"+e]=i;c.event.triggered=false}}},handle:function(a){var b,d,f,e;a=arguments[0]=c.event.fix(a||A.event);a.currentTarget=this;b=a.type.indexOf(".")<0&&!a.exclusive;
|
||||
if(!b){d=a.type.split(".");a.type=d.shift();f=new RegExp("(^|\\.)"+d.slice(0).sort().join("\\.(?:.*\\.)?")+"(\\.|$)")}e=c.data(this,"events");d=e[a.type];if(e&&d){d=d.slice(0);e=0;for(var j=d.length;e<j;e++){var i=d[e];if(b||f.test(i.namespace)){a.handler=i.handler;a.data=i.data;a.handleObj=i;i=i.handler.apply(this,arguments);if(i!==w){a.result=i;if(i===false){a.preventDefault();a.stopPropagation()}}if(a.isImmediatePropagationStopped())break}}}return a.result},props:"altKey attrChange attrName bubbles button cancelable charCode clientX clientY ctrlKey currentTarget data detail eventPhase fromElement handler keyCode layerX layerY metaKey newValue offsetX offsetY originalTarget pageX pageY prevValue relatedNode relatedTarget screenX screenY shiftKey srcElement target toElement view wheelDelta which".split(" "),
|
||||
fix:function(a){if(a[G])return a;var b=a;a=c.Event(b);for(var d=this.props.length,f;d;){f=this.props[--d];a[f]=b[f]}if(!a.target)a.target=a.srcElement||s;if(a.target.nodeType===3)a.target=a.target.parentNode;if(!a.relatedTarget&&a.fromElement)a.relatedTarget=a.fromElement===a.target?a.toElement:a.fromElement;if(a.pageX==null&&a.clientX!=null){b=s.documentElement;d=s.body;a.pageX=a.clientX+(b&&b.scrollLeft||d&&d.scrollLeft||0)-(b&&b.clientLeft||d&&d.clientLeft||0);a.pageY=a.clientY+(b&&b.scrollTop||
|
||||
d&&d.scrollTop||0)-(b&&b.clientTop||d&&d.clientTop||0)}if(!a.which&&(a.charCode||a.charCode===0?a.charCode:a.keyCode))a.which=a.charCode||a.keyCode;if(!a.metaKey&&a.ctrlKey)a.metaKey=a.ctrlKey;if(!a.which&&a.button!==w)a.which=a.button&1?1:a.button&2?3:a.button&4?2:0;return a},guid:1E8,proxy:c.proxy,special:{ready:{setup:c.bindReady,teardown:c.noop},live:{add:function(a){c.event.add(this,a.origType,c.extend({},a,{handler:oa}))},remove:function(a){var b=true,d=a.origType.replace(O,"");c.each(c.data(this,
|
||||
"events").live||[],function(){if(d===this.origType.replace(O,""))return b=false});b&&c.event.remove(this,a.origType,oa)}},beforeunload:{setup:function(a,b,d){if(this.setInterval)this.onbeforeunload=d;return false},teardown:function(a,b){if(this.onbeforeunload===b)this.onbeforeunload=null}}}};var Ca=s.removeEventListener?function(a,b,d){a.removeEventListener(b,d,false)}:function(a,b,d){a.detachEvent("on"+b,d)};c.Event=function(a){if(!this.preventDefault)return new c.Event(a);if(a&&a.type){this.originalEvent=
|
||||
a;this.type=a.type}else this.type=a;this.timeStamp=J();this[G]=true};c.Event.prototype={preventDefault:function(){this.isDefaultPrevented=Z;var a=this.originalEvent;if(a){a.preventDefault&&a.preventDefault();a.returnValue=false}},stopPropagation:function(){this.isPropagationStopped=Z;var a=this.originalEvent;if(a){a.stopPropagation&&a.stopPropagation();a.cancelBubble=true}},stopImmediatePropagation:function(){this.isImmediatePropagationStopped=Z;this.stopPropagation()},isDefaultPrevented:Y,isPropagationStopped:Y,
|
||||
isImmediatePropagationStopped:Y};var Da=function(a){var b=a.relatedTarget;try{for(;b&&b!==this;)b=b.parentNode;if(b!==this){a.type=a.data;c.event.handle.apply(this,arguments)}}catch(d){}},Ea=function(a){a.type=a.data;c.event.handle.apply(this,arguments)};c.each({mouseenter:"mouseover",mouseleave:"mouseout"},function(a,b){c.event.special[a]={setup:function(d){c.event.add(this,b,d&&d.selector?Ea:Da,a)},teardown:function(d){c.event.remove(this,b,d&&d.selector?Ea:Da)}}});if(!c.support.submitBubbles)c.event.special.submit=
|
||||
{setup:function(){if(this.nodeName.toLowerCase()!=="form"){c.event.add(this,"click.specialSubmit",function(a){var b=a.target,d=b.type;if((d==="submit"||d==="image")&&c(b).closest("form").length)return na("submit",this,arguments)});c.event.add(this,"keypress.specialSubmit",function(a){var b=a.target,d=b.type;if((d==="text"||d==="password")&&c(b).closest("form").length&&a.keyCode===13)return na("submit",this,arguments)})}else return false},teardown:function(){c.event.remove(this,".specialSubmit")}};
|
||||
if(!c.support.changeBubbles){var da=/textarea|input|select/i,ea,Fa=function(a){var b=a.type,d=a.value;if(b==="radio"||b==="checkbox")d=a.checked;else if(b==="select-multiple")d=a.selectedIndex>-1?c.map(a.options,function(f){return f.selected}).join("-"):"";else if(a.nodeName.toLowerCase()==="select")d=a.selectedIndex;return d},fa=function(a,b){var d=a.target,f,e;if(!(!da.test(d.nodeName)||d.readOnly)){f=c.data(d,"_change_data");e=Fa(d);if(a.type!=="focusout"||d.type!=="radio")c.data(d,"_change_data",
|
||||
e);if(!(f===w||e===f))if(f!=null||e){a.type="change";return c.event.trigger(a,b,d)}}};c.event.special.change={filters:{focusout:fa,click:function(a){var b=a.target,d=b.type;if(d==="radio"||d==="checkbox"||b.nodeName.toLowerCase()==="select")return fa.call(this,a)},keydown:function(a){var b=a.target,d=b.type;if(a.keyCode===13&&b.nodeName.toLowerCase()!=="textarea"||a.keyCode===32&&(d==="checkbox"||d==="radio")||d==="select-multiple")return fa.call(this,a)},beforeactivate:function(a){a=a.target;c.data(a,
|
||||
"_change_data",Fa(a))}},setup:function(){if(this.type==="file")return false;for(var a in ea)c.event.add(this,a+".specialChange",ea[a]);return da.test(this.nodeName)},teardown:function(){c.event.remove(this,".specialChange");return da.test(this.nodeName)}};ea=c.event.special.change.filters}s.addEventListener&&c.each({focus:"focusin",blur:"focusout"},function(a,b){function d(f){f=c.event.fix(f);f.type=b;return c.event.handle.call(this,f)}c.event.special[b]={setup:function(){this.addEventListener(a,
|
||||
d,true)},teardown:function(){this.removeEventListener(a,d,true)}}});c.each(["bind","one"],function(a,b){c.fn[b]=function(d,f,e){if(typeof d==="object"){for(var j in d)this[b](j,f,d[j],e);return this}if(c.isFunction(f)){e=f;f=w}var i=b==="one"?c.proxy(e,function(k){c(this).unbind(k,i);return e.apply(this,arguments)}):e;if(d==="unload"&&b!=="one")this.one(d,f,e);else{j=0;for(var o=this.length;j<o;j++)c.event.add(this[j],d,i,f)}return this}});c.fn.extend({unbind:function(a,b){if(typeof a==="object"&&
|
||||
!a.preventDefault)for(var d in a)this.unbind(d,a[d]);else{d=0;for(var f=this.length;d<f;d++)c.event.remove(this[d],a,b)}return this},delegate:function(a,b,d,f){return this.live(b,d,f,a)},undelegate:function(a,b,d){return arguments.length===0?this.unbind("live"):this.die(b,null,d,a)},trigger:function(a,b){return this.each(function(){c.event.trigger(a,b,this)})},triggerHandler:function(a,b){if(this[0]){a=c.Event(a);a.preventDefault();a.stopPropagation();c.event.trigger(a,b,this[0]);return a.result}},
|
||||
toggle:function(a){for(var b=arguments,d=1;d<b.length;)c.proxy(a,b[d++]);return this.click(c.proxy(a,function(f){var e=(c.data(this,"lastToggle"+a.guid)||0)%d;c.data(this,"lastToggle"+a.guid,e+1);f.preventDefault();return b[e].apply(this,arguments)||false}))},hover:function(a,b){return this.mouseenter(a).mouseleave(b||a)}});var Ga={focus:"focusin",blur:"focusout",mouseenter:"mouseover",mouseleave:"mouseout"};c.each(["live","die"],function(a,b){c.fn[b]=function(d,f,e,j){var i,o=0,k,n,r=j||this.selector,
|
||||
u=j?this:c(this.context);if(c.isFunction(f)){e=f;f=w}for(d=(d||"").split(" ");(i=d[o++])!=null;){j=O.exec(i);k="";if(j){k=j[0];i=i.replace(O,"")}if(i==="hover")d.push("mouseenter"+k,"mouseleave"+k);else{n=i;if(i==="focus"||i==="blur"){d.push(Ga[i]+k);i+=k}else i=(Ga[i]||i)+k;b==="live"?u.each(function(){c.event.add(this,pa(i,r),{data:f,selector:r,handler:e,origType:i,origHandler:e,preType:n})}):u.unbind(pa(i,r),e)}}return this}});c.each("blur focus focusin focusout load resize scroll unload click dblclick mousedown mouseup mousemove mouseover mouseout mouseenter mouseleave change select submit keydown keypress keyup error".split(" "),
|
||||
function(a,b){c.fn[b]=function(d){return d?this.bind(b,d):this.trigger(b)};if(c.attrFn)c.attrFn[b]=true});A.attachEvent&&!A.addEventListener&&A.attachEvent("onunload",function(){for(var a in c.cache)if(c.cache[a].handle)try{c.event.remove(c.cache[a].handle.elem)}catch(b){}});(function(){function a(g){for(var h="",l,m=0;g[m];m++){l=g[m];if(l.nodeType===3||l.nodeType===4)h+=l.nodeValue;else if(l.nodeType!==8)h+=a(l.childNodes)}return h}function b(g,h,l,m,q,p){q=0;for(var v=m.length;q<v;q++){var t=m[q];
|
||||
if(t){t=t[g];for(var y=false;t;){if(t.sizcache===l){y=m[t.sizset];break}if(t.nodeType===1&&!p){t.sizcache=l;t.sizset=q}if(t.nodeName.toLowerCase()===h){y=t;break}t=t[g]}m[q]=y}}}function d(g,h,l,m,q,p){q=0;for(var v=m.length;q<v;q++){var t=m[q];if(t){t=t[g];for(var y=false;t;){if(t.sizcache===l){y=m[t.sizset];break}if(t.nodeType===1){if(!p){t.sizcache=l;t.sizset=q}if(typeof h!=="string"){if(t===h){y=true;break}}else if(k.filter(h,[t]).length>0){y=t;break}}t=t[g]}m[q]=y}}}var f=/((?:\((?:\([^()]+\)|[^()]+)+\)|\[(?:\[[^[\]]*\]|['"][^'"]*['"]|[^[\]'"]+)+\]|\\.|[^ >+~,(\[\\]+)+|[>+~])(\s*,\s*)?((?:.|\r|\n)*)/g,
|
||||
e=0,j=Object.prototype.toString,i=false,o=true;[0,0].sort(function(){o=false;return 0});var k=function(g,h,l,m){l=l||[];var q=h=h||s;if(h.nodeType!==1&&h.nodeType!==9)return[];if(!g||typeof g!=="string")return l;for(var p=[],v,t,y,S,H=true,M=x(h),I=g;(f.exec(""),v=f.exec(I))!==null;){I=v[3];p.push(v[1]);if(v[2]){S=v[3];break}}if(p.length>1&&r.exec(g))if(p.length===2&&n.relative[p[0]])t=ga(p[0]+p[1],h);else for(t=n.relative[p[0]]?[h]:k(p.shift(),h);p.length;){g=p.shift();if(n.relative[g])g+=p.shift();
|
||||
t=ga(g,t)}else{if(!m&&p.length>1&&h.nodeType===9&&!M&&n.match.ID.test(p[0])&&!n.match.ID.test(p[p.length-1])){v=k.find(p.shift(),h,M);h=v.expr?k.filter(v.expr,v.set)[0]:v.set[0]}if(h){v=m?{expr:p.pop(),set:z(m)}:k.find(p.pop(),p.length===1&&(p[0]==="~"||p[0]==="+")&&h.parentNode?h.parentNode:h,M);t=v.expr?k.filter(v.expr,v.set):v.set;if(p.length>0)y=z(t);else H=false;for(;p.length;){var D=p.pop();v=D;if(n.relative[D])v=p.pop();else D="";if(v==null)v=h;n.relative[D](y,v,M)}}else y=[]}y||(y=t);y||k.error(D||
|
||||
g);if(j.call(y)==="[object Array]")if(H)if(h&&h.nodeType===1)for(g=0;y[g]!=null;g++){if(y[g]&&(y[g]===true||y[g].nodeType===1&&E(h,y[g])))l.push(t[g])}else for(g=0;y[g]!=null;g++)y[g]&&y[g].nodeType===1&&l.push(t[g]);else l.push.apply(l,y);else z(y,l);if(S){k(S,q,l,m);k.uniqueSort(l)}return l};k.uniqueSort=function(g){if(B){i=o;g.sort(B);if(i)for(var h=1;h<g.length;h++)g[h]===g[h-1]&&g.splice(h--,1)}return g};k.matches=function(g,h){return k(g,null,null,h)};k.find=function(g,h,l){var m,q;if(!g)return[];
|
||||
for(var p=0,v=n.order.length;p<v;p++){var t=n.order[p];if(q=n.leftMatch[t].exec(g)){var y=q[1];q.splice(1,1);if(y.substr(y.length-1)!=="\\"){q[1]=(q[1]||"").replace(/\\/g,"");m=n.find[t](q,h,l);if(m!=null){g=g.replace(n.match[t],"");break}}}}m||(m=h.getElementsByTagName("*"));return{set:m,expr:g}};k.filter=function(g,h,l,m){for(var q=g,p=[],v=h,t,y,S=h&&h[0]&&x(h[0]);g&&h.length;){for(var H in n.filter)if((t=n.leftMatch[H].exec(g))!=null&&t[2]){var M=n.filter[H],I,D;D=t[1];y=false;t.splice(1,1);if(D.substr(D.length-
|
||||
1)!=="\\"){if(v===p)p=[];if(n.preFilter[H])if(t=n.preFilter[H](t,v,l,p,m,S)){if(t===true)continue}else y=I=true;if(t)for(var U=0;(D=v[U])!=null;U++)if(D){I=M(D,t,U,v);var Ha=m^!!I;if(l&&I!=null)if(Ha)y=true;else v[U]=false;else if(Ha){p.push(D);y=true}}if(I!==w){l||(v=p);g=g.replace(n.match[H],"");if(!y)return[];break}}}if(g===q)if(y==null)k.error(g);else break;q=g}return v};k.error=function(g){throw"Syntax error, unrecognized expression: "+g;};var n=k.selectors={order:["ID","NAME","TAG"],match:{ID:/#((?:[\w\u00c0-\uFFFF-]|\\.)+)/,
|
||||
CLASS:/\.((?:[\w\u00c0-\uFFFF-]|\\.)+)/,NAME:/\[name=['"]*((?:[\w\u00c0-\uFFFF-]|\\.)+)['"]*\]/,ATTR:/\[\s*((?:[\w\u00c0-\uFFFF-]|\\.)+)\s*(?:(\S?=)\s*(['"]*)(.*?)\3|)\s*\]/,TAG:/^((?:[\w\u00c0-\uFFFF\*-]|\\.)+)/,CHILD:/:(only|nth|last|first)-child(?:\((even|odd|[\dn+-]*)\))?/,POS:/:(nth|eq|gt|lt|first|last|even|odd)(?:\((\d*)\))?(?=[^-]|$)/,PSEUDO:/:((?:[\w\u00c0-\uFFFF-]|\\.)+)(?:\((['"]?)((?:\([^\)]+\)|[^\(\)]*)+)\2\))?/},leftMatch:{},attrMap:{"class":"className","for":"htmlFor"},attrHandle:{href:function(g){return g.getAttribute("href")}},
|
||||
relative:{"+":function(g,h){var l=typeof h==="string",m=l&&!/\W/.test(h);l=l&&!m;if(m)h=h.toLowerCase();m=0;for(var q=g.length,p;m<q;m++)if(p=g[m]){for(;(p=p.previousSibling)&&p.nodeType!==1;);g[m]=l||p&&p.nodeName.toLowerCase()===h?p||false:p===h}l&&k.filter(h,g,true)},">":function(g,h){var l=typeof h==="string";if(l&&!/\W/.test(h)){h=h.toLowerCase();for(var m=0,q=g.length;m<q;m++){var p=g[m];if(p){l=p.parentNode;g[m]=l.nodeName.toLowerCase()===h?l:false}}}else{m=0;for(q=g.length;m<q;m++)if(p=g[m])g[m]=
|
||||
l?p.parentNode:p.parentNode===h;l&&k.filter(h,g,true)}},"":function(g,h,l){var m=e++,q=d;if(typeof h==="string"&&!/\W/.test(h)){var p=h=h.toLowerCase();q=b}q("parentNode",h,m,g,p,l)},"~":function(g,h,l){var m=e++,q=d;if(typeof h==="string"&&!/\W/.test(h)){var p=h=h.toLowerCase();q=b}q("previousSibling",h,m,g,p,l)}},find:{ID:function(g,h,l){if(typeof h.getElementById!=="undefined"&&!l)return(g=h.getElementById(g[1]))?[g]:[]},NAME:function(g,h){if(typeof h.getElementsByName!=="undefined"){var l=[];
|
||||
h=h.getElementsByName(g[1]);for(var m=0,q=h.length;m<q;m++)h[m].getAttribute("name")===g[1]&&l.push(h[m]);return l.length===0?null:l}},TAG:function(g,h){return h.getElementsByTagName(g[1])}},preFilter:{CLASS:function(g,h,l,m,q,p){g=" "+g[1].replace(/\\/g,"")+" ";if(p)return g;p=0;for(var v;(v=h[p])!=null;p++)if(v)if(q^(v.className&&(" "+v.className+" ").replace(/[\t\n]/g," ").indexOf(g)>=0))l||m.push(v);else if(l)h[p]=false;return false},ID:function(g){return g[1].replace(/\\/g,"")},TAG:function(g){return g[1].toLowerCase()},
|
||||
CHILD:function(g){if(g[1]==="nth"){var h=/(-?)(\d*)n((?:\+|-)?\d*)/.exec(g[2]==="even"&&"2n"||g[2]==="odd"&&"2n+1"||!/\D/.test(g[2])&&"0n+"+g[2]||g[2]);g[2]=h[1]+(h[2]||1)-0;g[3]=h[3]-0}g[0]=e++;return g},ATTR:function(g,h,l,m,q,p){h=g[1].replace(/\\/g,"");if(!p&&n.attrMap[h])g[1]=n.attrMap[h];if(g[2]==="~=")g[4]=" "+g[4]+" ";return g},PSEUDO:function(g,h,l,m,q){if(g[1]==="not")if((f.exec(g[3])||"").length>1||/^\w/.test(g[3]))g[3]=k(g[3],null,null,h);else{g=k.filter(g[3],h,l,true^q);l||m.push.apply(m,
|
||||
g);return false}else if(n.match.POS.test(g[0])||n.match.CHILD.test(g[0]))return true;return g},POS:function(g){g.unshift(true);return g}},filters:{enabled:function(g){return g.disabled===false&&g.type!=="hidden"},disabled:function(g){return g.disabled===true},checked:function(g){return g.checked===true},selected:function(g){return g.selected===true},parent:function(g){return!!g.firstChild},empty:function(g){return!g.firstChild},has:function(g,h,l){return!!k(l[3],g).length},header:function(g){return/h\d/i.test(g.nodeName)},
|
||||
text:function(g){return"text"===g.type},radio:function(g){return"radio"===g.type},checkbox:function(g){return"checkbox"===g.type},file:function(g){return"file"===g.type},password:function(g){return"password"===g.type},submit:function(g){return"submit"===g.type},image:function(g){return"image"===g.type},reset:function(g){return"reset"===g.type},button:function(g){return"button"===g.type||g.nodeName.toLowerCase()==="button"},input:function(g){return/input|select|textarea|button/i.test(g.nodeName)}},
|
||||
setFilters:{first:function(g,h){return h===0},last:function(g,h,l,m){return h===m.length-1},even:function(g,h){return h%2===0},odd:function(g,h){return h%2===1},lt:function(g,h,l){return h<l[3]-0},gt:function(g,h,l){return h>l[3]-0},nth:function(g,h,l){return l[3]-0===h},eq:function(g,h,l){return l[3]-0===h}},filter:{PSEUDO:function(g,h,l,m){var q=h[1],p=n.filters[q];if(p)return p(g,l,h,m);else if(q==="contains")return(g.textContent||g.innerText||a([g])||"").indexOf(h[3])>=0;else if(q==="not"){h=
|
||||
h[3];l=0;for(m=h.length;l<m;l++)if(h[l]===g)return false;return true}else k.error("Syntax error, unrecognized expression: "+q)},CHILD:function(g,h){var l=h[1],m=g;switch(l){case "only":case "first":for(;m=m.previousSibling;)if(m.nodeType===1)return false;if(l==="first")return true;m=g;case "last":for(;m=m.nextSibling;)if(m.nodeType===1)return false;return true;case "nth":l=h[2];var q=h[3];if(l===1&&q===0)return true;h=h[0];var p=g.parentNode;if(p&&(p.sizcache!==h||!g.nodeIndex)){var v=0;for(m=p.firstChild;m;m=
|
||||
m.nextSibling)if(m.nodeType===1)m.nodeIndex=++v;p.sizcache=h}g=g.nodeIndex-q;return l===0?g===0:g%l===0&&g/l>=0}},ID:function(g,h){return g.nodeType===1&&g.getAttribute("id")===h},TAG:function(g,h){return h==="*"&&g.nodeType===1||g.nodeName.toLowerCase()===h},CLASS:function(g,h){return(" "+(g.className||g.getAttribute("class"))+" ").indexOf(h)>-1},ATTR:function(g,h){var l=h[1];g=n.attrHandle[l]?n.attrHandle[l](g):g[l]!=null?g[l]:g.getAttribute(l);l=g+"";var m=h[2];h=h[4];return g==null?m==="!=":m===
|
||||
"="?l===h:m==="*="?l.indexOf(h)>=0:m==="~="?(" "+l+" ").indexOf(h)>=0:!h?l&&g!==false:m==="!="?l!==h:m==="^="?l.indexOf(h)===0:m==="$="?l.substr(l.length-h.length)===h:m==="|="?l===h||l.substr(0,h.length+1)===h+"-":false},POS:function(g,h,l,m){var q=n.setFilters[h[2]];if(q)return q(g,l,h,m)}}},r=n.match.POS;for(var u in n.match){n.match[u]=new RegExp(n.match[u].source+/(?![^\[]*\])(?![^\(]*\))/.source);n.leftMatch[u]=new RegExp(/(^(?:.|\r|\n)*?)/.source+n.match[u].source.replace(/\\(\d+)/g,function(g,
|
||||
h){return"\\"+(h-0+1)}))}var z=function(g,h){g=Array.prototype.slice.call(g,0);if(h){h.push.apply(h,g);return h}return g};try{Array.prototype.slice.call(s.documentElement.childNodes,0)}catch(C){z=function(g,h){h=h||[];if(j.call(g)==="[object Array]")Array.prototype.push.apply(h,g);else if(typeof g.length==="number")for(var l=0,m=g.length;l<m;l++)h.push(g[l]);else for(l=0;g[l];l++)h.push(g[l]);return h}}var B;if(s.documentElement.compareDocumentPosition)B=function(g,h){if(!g.compareDocumentPosition||
|
||||
!h.compareDocumentPosition){if(g==h)i=true;return g.compareDocumentPosition?-1:1}g=g.compareDocumentPosition(h)&4?-1:g===h?0:1;if(g===0)i=true;return g};else if("sourceIndex"in s.documentElement)B=function(g,h){if(!g.sourceIndex||!h.sourceIndex){if(g==h)i=true;return g.sourceIndex?-1:1}g=g.sourceIndex-h.sourceIndex;if(g===0)i=true;return g};else if(s.createRange)B=function(g,h){if(!g.ownerDocument||!h.ownerDocument){if(g==h)i=true;return g.ownerDocument?-1:1}var l=g.ownerDocument.createRange(),m=
|
||||
h.ownerDocument.createRange();l.setStart(g,0);l.setEnd(g,0);m.setStart(h,0);m.setEnd(h,0);g=l.compareBoundaryPoints(Range.START_TO_END,m);if(g===0)i=true;return g};(function(){var g=s.createElement("div"),h="script"+(new Date).getTime();g.innerHTML="<a name='"+h+"'/>";var l=s.documentElement;l.insertBefore(g,l.firstChild);if(s.getElementById(h)){n.find.ID=function(m,q,p){if(typeof q.getElementById!=="undefined"&&!p)return(q=q.getElementById(m[1]))?q.id===m[1]||typeof q.getAttributeNode!=="undefined"&&
|
||||
q.getAttributeNode("id").nodeValue===m[1]?[q]:w:[]};n.filter.ID=function(m,q){var p=typeof m.getAttributeNode!=="undefined"&&m.getAttributeNode("id");return m.nodeType===1&&p&&p.nodeValue===q}}l.removeChild(g);l=g=null})();(function(){var g=s.createElement("div");g.appendChild(s.createComment(""));if(g.getElementsByTagName("*").length>0)n.find.TAG=function(h,l){l=l.getElementsByTagName(h[1]);if(h[1]==="*"){h=[];for(var m=0;l[m];m++)l[m].nodeType===1&&h.push(l[m]);l=h}return l};g.innerHTML="<a href='#'></a>";
|
||||
if(g.firstChild&&typeof g.firstChild.getAttribute!=="undefined"&&g.firstChild.getAttribute("href")!=="#")n.attrHandle.href=function(h){return h.getAttribute("href",2)};g=null})();s.querySelectorAll&&function(){var g=k,h=s.createElement("div");h.innerHTML="<p class='TEST'></p>";if(!(h.querySelectorAll&&h.querySelectorAll(".TEST").length===0)){k=function(m,q,p,v){q=q||s;if(!v&&q.nodeType===9&&!x(q))try{return z(q.querySelectorAll(m),p)}catch(t){}return g(m,q,p,v)};for(var l in g)k[l]=g[l];h=null}}();
|
||||
(function(){var g=s.createElement("div");g.innerHTML="<div class='test e'></div><div class='test'></div>";if(!(!g.getElementsByClassName||g.getElementsByClassName("e").length===0)){g.lastChild.className="e";if(g.getElementsByClassName("e").length!==1){n.order.splice(1,0,"CLASS");n.find.CLASS=function(h,l,m){if(typeof l.getElementsByClassName!=="undefined"&&!m)return l.getElementsByClassName(h[1])};g=null}}})();var E=s.compareDocumentPosition?function(g,h){return!!(g.compareDocumentPosition(h)&16)}:
|
||||
function(g,h){return g!==h&&(g.contains?g.contains(h):true)},x=function(g){return(g=(g?g.ownerDocument||g:0).documentElement)?g.nodeName!=="HTML":false},ga=function(g,h){var l=[],m="",q;for(h=h.nodeType?[h]:h;q=n.match.PSEUDO.exec(g);){m+=q[0];g=g.replace(n.match.PSEUDO,"")}g=n.relative[g]?g+"*":g;q=0;for(var p=h.length;q<p;q++)k(g,h[q],l);return k.filter(m,l)};c.find=k;c.expr=k.selectors;c.expr[":"]=c.expr.filters;c.unique=k.uniqueSort;c.text=a;c.isXMLDoc=x;c.contains=E})();var eb=/Until$/,fb=/^(?:parents|prevUntil|prevAll)/,
|
||||
gb=/,/;R=Array.prototype.slice;var Ia=function(a,b,d){if(c.isFunction(b))return c.grep(a,function(e,j){return!!b.call(e,j,e)===d});else if(b.nodeType)return c.grep(a,function(e){return e===b===d});else if(typeof b==="string"){var f=c.grep(a,function(e){return e.nodeType===1});if(Ua.test(b))return c.filter(b,f,!d);else b=c.filter(b,f)}return c.grep(a,function(e){return c.inArray(e,b)>=0===d})};c.fn.extend({find:function(a){for(var b=this.pushStack("","find",a),d=0,f=0,e=this.length;f<e;f++){d=b.length;
|
||||
c.find(a,this[f],b);if(f>0)for(var j=d;j<b.length;j++)for(var i=0;i<d;i++)if(b[i]===b[j]){b.splice(j--,1);break}}return b},has:function(a){var b=c(a);return this.filter(function(){for(var d=0,f=b.length;d<f;d++)if(c.contains(this,b[d]))return true})},not:function(a){return this.pushStack(Ia(this,a,false),"not",a)},filter:function(a){return this.pushStack(Ia(this,a,true),"filter",a)},is:function(a){return!!a&&c.filter(a,this).length>0},closest:function(a,b){if(c.isArray(a)){var d=[],f=this[0],e,j=
|
||||
{},i;if(f&&a.length){e=0;for(var o=a.length;e<o;e++){i=a[e];j[i]||(j[i]=c.expr.match.POS.test(i)?c(i,b||this.context):i)}for(;f&&f.ownerDocument&&f!==b;){for(i in j){e=j[i];if(e.jquery?e.index(f)>-1:c(f).is(e)){d.push({selector:i,elem:f});delete j[i]}}f=f.parentNode}}return d}var k=c.expr.match.POS.test(a)?c(a,b||this.context):null;return this.map(function(n,r){for(;r&&r.ownerDocument&&r!==b;){if(k?k.index(r)>-1:c(r).is(a))return r;r=r.parentNode}return null})},index:function(a){if(!a||typeof a===
|
||||
"string")return c.inArray(this[0],a?c(a):this.parent().children());return c.inArray(a.jquery?a[0]:a,this)},add:function(a,b){a=typeof a==="string"?c(a,b||this.context):c.makeArray(a);b=c.merge(this.get(),a);return this.pushStack(qa(a[0])||qa(b[0])?b:c.unique(b))},andSelf:function(){return this.add(this.prevObject)}});c.each({parent:function(a){return(a=a.parentNode)&&a.nodeType!==11?a:null},parents:function(a){return c.dir(a,"parentNode")},parentsUntil:function(a,b,d){return c.dir(a,"parentNode",
|
||||
d)},next:function(a){return c.nth(a,2,"nextSibling")},prev:function(a){return c.nth(a,2,"previousSibling")},nextAll:function(a){return c.dir(a,"nextSibling")},prevAll:function(a){return c.dir(a,"previousSibling")},nextUntil:function(a,b,d){return c.dir(a,"nextSibling",d)},prevUntil:function(a,b,d){return c.dir(a,"previousSibling",d)},siblings:function(a){return c.sibling(a.parentNode.firstChild,a)},children:function(a){return c.sibling(a.firstChild)},contents:function(a){return c.nodeName(a,"iframe")?
|
||||
a.contentDocument||a.contentWindow.document:c.makeArray(a.childNodes)}},function(a,b){c.fn[a]=function(d,f){var e=c.map(this,b,d);eb.test(a)||(f=d);if(f&&typeof f==="string")e=c.filter(f,e);e=this.length>1?c.unique(e):e;if((this.length>1||gb.test(f))&&fb.test(a))e=e.reverse();return this.pushStack(e,a,R.call(arguments).join(","))}});c.extend({filter:function(a,b,d){if(d)a=":not("+a+")";return c.find.matches(a,b)},dir:function(a,b,d){var f=[];for(a=a[b];a&&a.nodeType!==9&&(d===w||a.nodeType!==1||!c(a).is(d));){a.nodeType===
|
||||
1&&f.push(a);a=a[b]}return f},nth:function(a,b,d){b=b||1;for(var f=0;a;a=a[d])if(a.nodeType===1&&++f===b)break;return a},sibling:function(a,b){for(var d=[];a;a=a.nextSibling)a.nodeType===1&&a!==b&&d.push(a);return d}});var Ja=/ jQuery\d+="(?:\d+|null)"/g,V=/^\s+/,Ka=/(<([\w:]+)[^>]*?)\/>/g,hb=/^(?:area|br|col|embed|hr|img|input|link|meta|param)$/i,La=/<([\w:]+)/,ib=/<tbody/i,jb=/<|&#?\w+;/,ta=/<script|<object|<embed|<option|<style/i,ua=/checked\s*(?:[^=]|=\s*.checked.)/i,Ma=function(a,b,d){return hb.test(d)?
|
||||
a:b+"></"+d+">"},F={option:[1,"<select multiple='multiple'>","</select>"],legend:[1,"<fieldset>","</fieldset>"],thead:[1,"<table>","</table>"],tr:[2,"<table><tbody>","</tbody></table>"],td:[3,"<table><tbody><tr>","</tr></tbody></table>"],col:[2,"<table><tbody></tbody><colgroup>","</colgroup></table>"],area:[1,"<map>","</map>"],_default:[0,"",""]};F.optgroup=F.option;F.tbody=F.tfoot=F.colgroup=F.caption=F.thead;F.th=F.td;if(!c.support.htmlSerialize)F._default=[1,"div<div>","</div>"];c.fn.extend({text:function(a){if(c.isFunction(a))return this.each(function(b){var d=
|
||||
c(this);d.text(a.call(this,b,d.text()))});if(typeof a!=="object"&&a!==w)return this.empty().append((this[0]&&this[0].ownerDocument||s).createTextNode(a));return c.text(this)},wrapAll:function(a){if(c.isFunction(a))return this.each(function(d){c(this).wrapAll(a.call(this,d))});if(this[0]){var b=c(a,this[0].ownerDocument).eq(0).clone(true);this[0].parentNode&&b.insertBefore(this[0]);b.map(function(){for(var d=this;d.firstChild&&d.firstChild.nodeType===1;)d=d.firstChild;return d}).append(this)}return this},
|
||||
wrapInner:function(a){if(c.isFunction(a))return this.each(function(b){c(this).wrapInner(a.call(this,b))});return this.each(function(){var b=c(this),d=b.contents();d.length?d.wrapAll(a):b.append(a)})},wrap:function(a){return this.each(function(){c(this).wrapAll(a)})},unwrap:function(){return this.parent().each(function(){c.nodeName(this,"body")||c(this).replaceWith(this.childNodes)}).end()},append:function(){return this.domManip(arguments,true,function(a){this.nodeType===1&&this.appendChild(a)})},
|
||||
prepend:function(){return this.domManip(arguments,true,function(a){this.nodeType===1&&this.insertBefore(a,this.firstChild)})},before:function(){if(this[0]&&this[0].parentNode)return this.domManip(arguments,false,function(b){this.parentNode.insertBefore(b,this)});else if(arguments.length){var a=c(arguments[0]);a.push.apply(a,this.toArray());return this.pushStack(a,"before",arguments)}},after:function(){if(this[0]&&this[0].parentNode)return this.domManip(arguments,false,function(b){this.parentNode.insertBefore(b,
|
||||
this.nextSibling)});else if(arguments.length){var a=this.pushStack(this,"after",arguments);a.push.apply(a,c(arguments[0]).toArray());return a}},remove:function(a,b){for(var d=0,f;(f=this[d])!=null;d++)if(!a||c.filter(a,[f]).length){if(!b&&f.nodeType===1){c.cleanData(f.getElementsByTagName("*"));c.cleanData([f])}f.parentNode&&f.parentNode.removeChild(f)}return this},empty:function(){for(var a=0,b;(b=this[a])!=null;a++)for(b.nodeType===1&&c.cleanData(b.getElementsByTagName("*"));b.firstChild;)b.removeChild(b.firstChild);
|
||||
return this},clone:function(a){var b=this.map(function(){if(!c.support.noCloneEvent&&!c.isXMLDoc(this)){var d=this.outerHTML,f=this.ownerDocument;if(!d){d=f.createElement("div");d.appendChild(this.cloneNode(true));d=d.innerHTML}return c.clean([d.replace(Ja,"").replace(/=([^="'>\s]+\/)>/g,'="$1">').replace(V,"")],f)[0]}else return this.cloneNode(true)});if(a===true){ra(this,b);ra(this.find("*"),b.find("*"))}return b},html:function(a){if(a===w)return this[0]&&this[0].nodeType===1?this[0].innerHTML.replace(Ja,
|
||||
""):null;else if(typeof a==="string"&&!ta.test(a)&&(c.support.leadingWhitespace||!V.test(a))&&!F[(La.exec(a)||["",""])[1].toLowerCase()]){a=a.replace(Ka,Ma);try{for(var b=0,d=this.length;b<d;b++)if(this[b].nodeType===1){c.cleanData(this[b].getElementsByTagName("*"));this[b].innerHTML=a}}catch(f){this.empty().append(a)}}else c.isFunction(a)?this.each(function(e){var j=c(this),i=j.html();j.empty().append(function(){return a.call(this,e,i)})}):this.empty().append(a);return this},replaceWith:function(a){if(this[0]&&
|
||||
this[0].parentNode){if(c.isFunction(a))return this.each(function(b){var d=c(this),f=d.html();d.replaceWith(a.call(this,b,f))});if(typeof a!=="string")a=c(a).detach();return this.each(function(){var b=this.nextSibling,d=this.parentNode;c(this).remove();b?c(b).before(a):c(d).append(a)})}else return this.pushStack(c(c.isFunction(a)?a():a),"replaceWith",a)},detach:function(a){return this.remove(a,true)},domManip:function(a,b,d){function f(u){return c.nodeName(u,"table")?u.getElementsByTagName("tbody")[0]||
|
||||
u.appendChild(u.ownerDocument.createElement("tbody")):u}var e,j,i=a[0],o=[],k;if(!c.support.checkClone&&arguments.length===3&&typeof i==="string"&&ua.test(i))return this.each(function(){c(this).domManip(a,b,d,true)});if(c.isFunction(i))return this.each(function(u){var z=c(this);a[0]=i.call(this,u,b?z.html():w);z.domManip(a,b,d)});if(this[0]){e=i&&i.parentNode;e=c.support.parentNode&&e&&e.nodeType===11&&e.childNodes.length===this.length?{fragment:e}:sa(a,this,o);k=e.fragment;if(j=k.childNodes.length===
|
||||
1?(k=k.firstChild):k.firstChild){b=b&&c.nodeName(j,"tr");for(var n=0,r=this.length;n<r;n++)d.call(b?f(this[n],j):this[n],n>0||e.cacheable||this.length>1?k.cloneNode(true):k)}o.length&&c.each(o,Qa)}return this}});c.fragments={};c.each({appendTo:"append",prependTo:"prepend",insertBefore:"before",insertAfter:"after",replaceAll:"replaceWith"},function(a,b){c.fn[a]=function(d){var f=[];d=c(d);var e=this.length===1&&this[0].parentNode;if(e&&e.nodeType===11&&e.childNodes.length===1&&d.length===1){d[b](this[0]);
|
||||
return this}else{e=0;for(var j=d.length;e<j;e++){var i=(e>0?this.clone(true):this).get();c.fn[b].apply(c(d[e]),i);f=f.concat(i)}return this.pushStack(f,a,d.selector)}}});c.extend({clean:function(a,b,d,f){b=b||s;if(typeof b.createElement==="undefined")b=b.ownerDocument||b[0]&&b[0].ownerDocument||s;for(var e=[],j=0,i;(i=a[j])!=null;j++){if(typeof i==="number")i+="";if(i){if(typeof i==="string"&&!jb.test(i))i=b.createTextNode(i);else if(typeof i==="string"){i=i.replace(Ka,Ma);var o=(La.exec(i)||["",
|
||||
""])[1].toLowerCase(),k=F[o]||F._default,n=k[0],r=b.createElement("div");for(r.innerHTML=k[1]+i+k[2];n--;)r=r.lastChild;if(!c.support.tbody){n=ib.test(i);o=o==="table"&&!n?r.firstChild&&r.firstChild.childNodes:k[1]==="<table>"&&!n?r.childNodes:[];for(k=o.length-1;k>=0;--k)c.nodeName(o[k],"tbody")&&!o[k].childNodes.length&&o[k].parentNode.removeChild(o[k])}!c.support.leadingWhitespace&&V.test(i)&&r.insertBefore(b.createTextNode(V.exec(i)[0]),r.firstChild);i=r.childNodes}if(i.nodeType)e.push(i);else e=
|
||||
c.merge(e,i)}}if(d)for(j=0;e[j];j++)if(f&&c.nodeName(e[j],"script")&&(!e[j].type||e[j].type.toLowerCase()==="text/javascript"))f.push(e[j].parentNode?e[j].parentNode.removeChild(e[j]):e[j]);else{e[j].nodeType===1&&e.splice.apply(e,[j+1,0].concat(c.makeArray(e[j].getElementsByTagName("script"))));d.appendChild(e[j])}return e},cleanData:function(a){for(var b,d,f=c.cache,e=c.event.special,j=c.support.deleteExpando,i=0,o;(o=a[i])!=null;i++)if(d=o[c.expando]){b=f[d];if(b.events)for(var k in b.events)e[k]?
|
||||
c.event.remove(o,k):Ca(o,k,b.handle);if(j)delete o[c.expando];else o.removeAttribute&&o.removeAttribute(c.expando);delete f[d]}}});var kb=/z-?index|font-?weight|opacity|zoom|line-?height/i,Na=/alpha\([^)]*\)/,Oa=/opacity=([^)]*)/,ha=/float/i,ia=/-([a-z])/ig,lb=/([A-Z])/g,mb=/^-?\d+(?:px)?$/i,nb=/^-?\d/,ob={position:"absolute",visibility:"hidden",display:"block"},pb=["Left","Right"],qb=["Top","Bottom"],rb=s.defaultView&&s.defaultView.getComputedStyle,Pa=c.support.cssFloat?"cssFloat":"styleFloat",ja=
|
||||
function(a,b){return b.toUpperCase()};c.fn.css=function(a,b){return X(this,a,b,true,function(d,f,e){if(e===w)return c.curCSS(d,f);if(typeof e==="number"&&!kb.test(f))e+="px";c.style(d,f,e)})};c.extend({style:function(a,b,d){if(!a||a.nodeType===3||a.nodeType===8)return w;if((b==="width"||b==="height")&&parseFloat(d)<0)d=w;var f=a.style||a,e=d!==w;if(!c.support.opacity&&b==="opacity"){if(e){f.zoom=1;b=parseInt(d,10)+""==="NaN"?"":"alpha(opacity="+d*100+")";a=f.filter||c.curCSS(a,"filter")||"";f.filter=
|
||||
Na.test(a)?a.replace(Na,b):b}return f.filter&&f.filter.indexOf("opacity=")>=0?parseFloat(Oa.exec(f.filter)[1])/100+"":""}if(ha.test(b))b=Pa;b=b.replace(ia,ja);if(e)f[b]=d;return f[b]},css:function(a,b,d,f){if(b==="width"||b==="height"){var e,j=b==="width"?pb:qb;function i(){e=b==="width"?a.offsetWidth:a.offsetHeight;f!=="border"&&c.each(j,function(){f||(e-=parseFloat(c.curCSS(a,"padding"+this,true))||0);if(f==="margin")e+=parseFloat(c.curCSS(a,"margin"+this,true))||0;else e-=parseFloat(c.curCSS(a,
|
||||
"border"+this+"Width",true))||0})}a.offsetWidth!==0?i():c.swap(a,ob,i);return Math.max(0,Math.round(e))}return c.curCSS(a,b,d)},curCSS:function(a,b,d){var f,e=a.style;if(!c.support.opacity&&b==="opacity"&&a.currentStyle){f=Oa.test(a.currentStyle.filter||"")?parseFloat(RegExp.$1)/100+"":"";return f===""?"1":f}if(ha.test(b))b=Pa;if(!d&&e&&e[b])f=e[b];else if(rb){if(ha.test(b))b="float";b=b.replace(lb,"-$1").toLowerCase();e=a.ownerDocument.defaultView;if(!e)return null;if(a=e.getComputedStyle(a,null))f=
|
||||
a.getPropertyValue(b);if(b==="opacity"&&f==="")f="1"}else if(a.currentStyle){d=b.replace(ia,ja);f=a.currentStyle[b]||a.currentStyle[d];if(!mb.test(f)&&nb.test(f)){b=e.left;var j=a.runtimeStyle.left;a.runtimeStyle.left=a.currentStyle.left;e.left=d==="fontSize"?"1em":f||0;f=e.pixelLeft+"px";e.left=b;a.runtimeStyle.left=j}}return f},swap:function(a,b,d){var f={};for(var e in b){f[e]=a.style[e];a.style[e]=b[e]}d.call(a);for(e in b)a.style[e]=f[e]}});if(c.expr&&c.expr.filters){c.expr.filters.hidden=function(a){var b=
|
||||
a.offsetWidth,d=a.offsetHeight,f=a.nodeName.toLowerCase()==="tr";return b===0&&d===0&&!f?true:b>0&&d>0&&!f?false:c.curCSS(a,"display")==="none"};c.expr.filters.visible=function(a){return!c.expr.filters.hidden(a)}}var sb=J(),tb=/<script(.|\s)*?\/script>/gi,ub=/select|textarea/i,vb=/color|date|datetime|email|hidden|month|number|password|range|search|tel|text|time|url|week/i,N=/=\?(&|$)/,ka=/\?/,wb=/(\?|&)_=.*?(&|$)/,xb=/^(\w+:)?\/\/([^\/?#]+)/,yb=/%20/g,zb=c.fn.load;c.fn.extend({load:function(a,b,d){if(typeof a!==
|
||||
"string")return zb.call(this,a);else if(!this.length)return this;var f=a.indexOf(" ");if(f>=0){var e=a.slice(f,a.length);a=a.slice(0,f)}f="GET";if(b)if(c.isFunction(b)){d=b;b=null}else if(typeof b==="object"){b=c.param(b,c.ajaxSettings.traditional);f="POST"}var j=this;c.ajax({url:a,type:f,dataType:"html",data:b,complete:function(i,o){if(o==="success"||o==="notmodified")j.html(e?c("<div />").append(i.responseText.replace(tb,"")).find(e):i.responseText);d&&j.each(d,[i.responseText,o,i])}});return this},
|
||||
serialize:function(){return c.param(this.serializeArray())},serializeArray:function(){return this.map(function(){return this.elements?c.makeArray(this.elements):this}).filter(function(){return this.name&&!this.disabled&&(this.checked||ub.test(this.nodeName)||vb.test(this.type))}).map(function(a,b){a=c(this).val();return a==null?null:c.isArray(a)?c.map(a,function(d){return{name:b.name,value:d}}):{name:b.name,value:a}}).get()}});c.each("ajaxStart ajaxStop ajaxComplete ajaxError ajaxSuccess ajaxSend".split(" "),
|
||||
function(a,b){c.fn[b]=function(d){return this.bind(b,d)}});c.extend({get:function(a,b,d,f){if(c.isFunction(b)){f=f||d;d=b;b=null}return c.ajax({type:"GET",url:a,data:b,success:d,dataType:f})},getScript:function(a,b){return c.get(a,null,b,"script")},getJSON:function(a,b,d){return c.get(a,b,d,"json")},post:function(a,b,d,f){if(c.isFunction(b)){f=f||d;d=b;b={}}return c.ajax({type:"POST",url:a,data:b,success:d,dataType:f})},ajaxSetup:function(a){c.extend(c.ajaxSettings,a)},ajaxSettings:{url:location.href,
|
||||
global:true,type:"GET",contentType:"application/x-www-form-urlencoded",processData:true,async:true,xhr:A.XMLHttpRequest&&(A.location.protocol!=="file:"||!A.ActiveXObject)?function(){return new A.XMLHttpRequest}:function(){try{return new A.ActiveXObject("Microsoft.XMLHTTP")}catch(a){}},accepts:{xml:"application/xml, text/xml",html:"text/html",script:"text/javascript, application/javascript",json:"application/json, text/javascript",text:"text/plain",_default:"*/*"}},lastModified:{},etag:{},ajax:function(a){function b(){e.success&&
|
||||
e.success.call(k,o,i,x);e.global&&f("ajaxSuccess",[x,e])}function d(){e.complete&&e.complete.call(k,x,i);e.global&&f("ajaxComplete",[x,e]);e.global&&!--c.active&&c.event.trigger("ajaxStop")}function f(q,p){(e.context?c(e.context):c.event).trigger(q,p)}var e=c.extend(true,{},c.ajaxSettings,a),j,i,o,k=a&&a.context||e,n=e.type.toUpperCase();if(e.data&&e.processData&&typeof e.data!=="string")e.data=c.param(e.data,e.traditional);if(e.dataType==="jsonp"){if(n==="GET")N.test(e.url)||(e.url+=(ka.test(e.url)?
|
||||
"&":"?")+(e.jsonp||"callback")+"=?");else if(!e.data||!N.test(e.data))e.data=(e.data?e.data+"&":"")+(e.jsonp||"callback")+"=?";e.dataType="json"}if(e.dataType==="json"&&(e.data&&N.test(e.data)||N.test(e.url))){j=e.jsonpCallback||"jsonp"+sb++;if(e.data)e.data=(e.data+"").replace(N,"="+j+"$1");e.url=e.url.replace(N,"="+j+"$1");e.dataType="script";A[j]=A[j]||function(q){o=q;b();d();A[j]=w;try{delete A[j]}catch(p){}z&&z.removeChild(C)}}if(e.dataType==="script"&&e.cache===null)e.cache=false;if(e.cache===
|
||||
false&&n==="GET"){var r=J(),u=e.url.replace(wb,"$1_="+r+"$2");e.url=u+(u===e.url?(ka.test(e.url)?"&":"?")+"_="+r:"")}if(e.data&&n==="GET")e.url+=(ka.test(e.url)?"&":"?")+e.data;e.global&&!c.active++&&c.event.trigger("ajaxStart");r=(r=xb.exec(e.url))&&(r[1]&&r[1]!==location.protocol||r[2]!==location.host);if(e.dataType==="script"&&n==="GET"&&r){var z=s.getElementsByTagName("head")[0]||s.documentElement,C=s.createElement("script");C.src=e.url;if(e.scriptCharset)C.charset=e.scriptCharset;if(!j){var B=
|
||||
false;C.onload=C.onreadystatechange=function(){if(!B&&(!this.readyState||this.readyState==="loaded"||this.readyState==="complete")){B=true;b();d();C.onload=C.onreadystatechange=null;z&&C.parentNode&&z.removeChild(C)}}}z.insertBefore(C,z.firstChild);return w}var E=false,x=e.xhr();if(x){e.username?x.open(n,e.url,e.async,e.username,e.password):x.open(n,e.url,e.async);try{if(e.data||a&&a.contentType)x.setRequestHeader("Content-Type",e.contentType);if(e.ifModified){c.lastModified[e.url]&&x.setRequestHeader("If-Modified-Since",
|
||||
c.lastModified[e.url]);c.etag[e.url]&&x.setRequestHeader("If-None-Match",c.etag[e.url])}r||x.setRequestHeader("X-Requested-With","XMLHttpRequest");x.setRequestHeader("Accept",e.dataType&&e.accepts[e.dataType]?e.accepts[e.dataType]+", */*":e.accepts._default)}catch(ga){}if(e.beforeSend&&e.beforeSend.call(k,x,e)===false){e.global&&!--c.active&&c.event.trigger("ajaxStop");x.abort();return false}e.global&&f("ajaxSend",[x,e]);var g=x.onreadystatechange=function(q){if(!x||x.readyState===0||q==="abort"){E||
|
||||
d();E=true;if(x)x.onreadystatechange=c.noop}else if(!E&&x&&(x.readyState===4||q==="timeout")){E=true;x.onreadystatechange=c.noop;i=q==="timeout"?"timeout":!c.httpSuccess(x)?"error":e.ifModified&&c.httpNotModified(x,e.url)?"notmodified":"success";var p;if(i==="success")try{o=c.httpData(x,e.dataType,e)}catch(v){i="parsererror";p=v}if(i==="success"||i==="notmodified")j||b();else c.handleError(e,x,i,p);d();q==="timeout"&&x.abort();if(e.async)x=null}};try{var h=x.abort;x.abort=function(){x&&h.call(x);
|
||||
g("abort")}}catch(l){}e.async&&e.timeout>0&&setTimeout(function(){x&&!E&&g("timeout")},e.timeout);try{x.send(n==="POST"||n==="PUT"||n==="DELETE"?e.data:null)}catch(m){c.handleError(e,x,null,m);d()}e.async||g();return x}},handleError:function(a,b,d,f){if(a.error)a.error.call(a.context||a,b,d,f);if(a.global)(a.context?c(a.context):c.event).trigger("ajaxError",[b,a,f])},active:0,httpSuccess:function(a){try{return!a.status&&location.protocol==="file:"||a.status>=200&&a.status<300||a.status===304||a.status===
|
||||
1223||a.status===0}catch(b){}return false},httpNotModified:function(a,b){var d=a.getResponseHeader("Last-Modified"),f=a.getResponseHeader("Etag");if(d)c.lastModified[b]=d;if(f)c.etag[b]=f;return a.status===304||a.status===0},httpData:function(a,b,d){var f=a.getResponseHeader("content-type")||"",e=b==="xml"||!b&&f.indexOf("xml")>=0;a=e?a.responseXML:a.responseText;e&&a.documentElement.nodeName==="parsererror"&&c.error("parsererror");if(d&&d.dataFilter)a=d.dataFilter(a,b);if(typeof a==="string")if(b===
|
||||
"json"||!b&&f.indexOf("json")>=0)a=c.parseJSON(a);else if(b==="script"||!b&&f.indexOf("javascript")>=0)c.globalEval(a);return a},param:function(a,b){function d(i,o){if(c.isArray(o))c.each(o,function(k,n){b||/\[\]$/.test(i)?f(i,n):d(i+"["+(typeof n==="object"||c.isArray(n)?k:"")+"]",n)});else!b&&o!=null&&typeof o==="object"?c.each(o,function(k,n){d(i+"["+k+"]",n)}):f(i,o)}function f(i,o){o=c.isFunction(o)?o():o;e[e.length]=encodeURIComponent(i)+"="+encodeURIComponent(o)}var e=[];if(b===w)b=c.ajaxSettings.traditional;
|
||||
if(c.isArray(a)||a.jquery)c.each(a,function(){f(this.name,this.value)});else for(var j in a)d(j,a[j]);return e.join("&").replace(yb,"+")}});var la={},Ab=/toggle|show|hide/,Bb=/^([+-]=)?([\d+-.]+)(.*)$/,W,va=[["height","marginTop","marginBottom","paddingTop","paddingBottom"],["width","marginLeft","marginRight","paddingLeft","paddingRight"],["opacity"]];c.fn.extend({show:function(a,b){if(a||a===0)return this.animate(K("show",3),a,b);else{a=0;for(b=this.length;a<b;a++){var d=c.data(this[a],"olddisplay");
|
||||
this[a].style.display=d||"";if(c.css(this[a],"display")==="none"){d=this[a].nodeName;var f;if(la[d])f=la[d];else{var e=c("<"+d+" />").appendTo("body");f=e.css("display");if(f==="none")f="block";e.remove();la[d]=f}c.data(this[a],"olddisplay",f)}}a=0;for(b=this.length;a<b;a++)this[a].style.display=c.data(this[a],"olddisplay")||"";return this}},hide:function(a,b){if(a||a===0)return this.animate(K("hide",3),a,b);else{a=0;for(b=this.length;a<b;a++){var d=c.data(this[a],"olddisplay");!d&&d!=="none"&&c.data(this[a],
|
||||
"olddisplay",c.css(this[a],"display"))}a=0;for(b=this.length;a<b;a++)this[a].style.display="none";return this}},_toggle:c.fn.toggle,toggle:function(a,b){var d=typeof a==="boolean";if(c.isFunction(a)&&c.isFunction(b))this._toggle.apply(this,arguments);else a==null||d?this.each(function(){var f=d?a:c(this).is(":hidden");c(this)[f?"show":"hide"]()}):this.animate(K("toggle",3),a,b);return this},fadeTo:function(a,b,d){return this.filter(":hidden").css("opacity",0).show().end().animate({opacity:b},a,d)},
|
||||
animate:function(a,b,d,f){var e=c.speed(b,d,f);if(c.isEmptyObject(a))return this.each(e.complete);return this[e.queue===false?"each":"queue"](function(){var j=c.extend({},e),i,o=this.nodeType===1&&c(this).is(":hidden"),k=this;for(i in a){var n=i.replace(ia,ja);if(i!==n){a[n]=a[i];delete a[i];i=n}if(a[i]==="hide"&&o||a[i]==="show"&&!o)return j.complete.call(this);if((i==="height"||i==="width")&&this.style){j.display=c.css(this,"display");j.overflow=this.style.overflow}if(c.isArray(a[i])){(j.specialEasing=
|
||||
j.specialEasing||{})[i]=a[i][1];a[i]=a[i][0]}}if(j.overflow!=null)this.style.overflow="hidden";j.curAnim=c.extend({},a);c.each(a,function(r,u){var z=new c.fx(k,j,r);if(Ab.test(u))z[u==="toggle"?o?"show":"hide":u](a);else{var C=Bb.exec(u),B=z.cur(true)||0;if(C){u=parseFloat(C[2]);var E=C[3]||"px";if(E!=="px"){k.style[r]=(u||1)+E;B=(u||1)/z.cur(true)*B;k.style[r]=B+E}if(C[1])u=(C[1]==="-="?-1:1)*u+B;z.custom(B,u,E)}else z.custom(B,u,"")}});return true})},stop:function(a,b){var d=c.timers;a&&this.queue([]);
|
||||
this.each(function(){for(var f=d.length-1;f>=0;f--)if(d[f].elem===this){b&&d[f](true);d.splice(f,1)}});b||this.dequeue();return this}});c.each({slideDown:K("show",1),slideUp:K("hide",1),slideToggle:K("toggle",1),fadeIn:{opacity:"show"},fadeOut:{opacity:"hide"}},function(a,b){c.fn[a]=function(d,f){return this.animate(b,d,f)}});c.extend({speed:function(a,b,d){var f=a&&typeof a==="object"?a:{complete:d||!d&&b||c.isFunction(a)&&a,duration:a,easing:d&&b||b&&!c.isFunction(b)&&b};f.duration=c.fx.off?0:typeof f.duration===
|
||||
"number"?f.duration:c.fx.speeds[f.duration]||c.fx.speeds._default;f.old=f.complete;f.complete=function(){f.queue!==false&&c(this).dequeue();c.isFunction(f.old)&&f.old.call(this)};return f},easing:{linear:function(a,b,d,f){return d+f*a},swing:function(a,b,d,f){return(-Math.cos(a*Math.PI)/2+0.5)*f+d}},timers:[],fx:function(a,b,d){this.options=b;this.elem=a;this.prop=d;if(!b.orig)b.orig={}}});c.fx.prototype={update:function(){this.options.step&&this.options.step.call(this.elem,this.now,this);(c.fx.step[this.prop]||
|
||||
c.fx.step._default)(this);if((this.prop==="height"||this.prop==="width")&&this.elem.style)this.elem.style.display="block"},cur:function(a){if(this.elem[this.prop]!=null&&(!this.elem.style||this.elem.style[this.prop]==null))return this.elem[this.prop];return(a=parseFloat(c.css(this.elem,this.prop,a)))&&a>-10000?a:parseFloat(c.curCSS(this.elem,this.prop))||0},custom:function(a,b,d){function f(j){return e.step(j)}this.startTime=J();this.start=a;this.end=b;this.unit=d||this.unit||"px";this.now=this.start;
|
||||
this.pos=this.state=0;var e=this;f.elem=this.elem;if(f()&&c.timers.push(f)&&!W)W=setInterval(c.fx.tick,13)},show:function(){this.options.orig[this.prop]=c.style(this.elem,this.prop);this.options.show=true;this.custom(this.prop==="width"||this.prop==="height"?1:0,this.cur());c(this.elem).show()},hide:function(){this.options.orig[this.prop]=c.style(this.elem,this.prop);this.options.hide=true;this.custom(this.cur(),0)},step:function(a){var b=J(),d=true;if(a||b>=this.options.duration+this.startTime){this.now=
|
||||
this.end;this.pos=this.state=1;this.update();this.options.curAnim[this.prop]=true;for(var f in this.options.curAnim)if(this.options.curAnim[f]!==true)d=false;if(d){if(this.options.display!=null){this.elem.style.overflow=this.options.overflow;a=c.data(this.elem,"olddisplay");this.elem.style.display=a?a:this.options.display;if(c.css(this.elem,"display")==="none")this.elem.style.display="block"}this.options.hide&&c(this.elem).hide();if(this.options.hide||this.options.show)for(var e in this.options.curAnim)c.style(this.elem,
|
||||
e,this.options.orig[e]);this.options.complete.call(this.elem)}return false}else{e=b-this.startTime;this.state=e/this.options.duration;a=this.options.easing||(c.easing.swing?"swing":"linear");this.pos=c.easing[this.options.specialEasing&&this.options.specialEasing[this.prop]||a](this.state,e,0,1,this.options.duration);this.now=this.start+(this.end-this.start)*this.pos;this.update()}return true}};c.extend(c.fx,{tick:function(){for(var a=c.timers,b=0;b<a.length;b++)a[b]()||a.splice(b--,1);a.length||
|
||||
c.fx.stop()},stop:function(){clearInterval(W);W=null},speeds:{slow:600,fast:200,_default:400},step:{opacity:function(a){c.style(a.elem,"opacity",a.now)},_default:function(a){if(a.elem.style&&a.elem.style[a.prop]!=null)a.elem.style[a.prop]=(a.prop==="width"||a.prop==="height"?Math.max(0,a.now):a.now)+a.unit;else a.elem[a.prop]=a.now}}});if(c.expr&&c.expr.filters)c.expr.filters.animated=function(a){return c.grep(c.timers,function(b){return a===b.elem}).length};c.fn.offset="getBoundingClientRect"in s.documentElement?
|
||||
function(a){var b=this[0];if(a)return this.each(function(e){c.offset.setOffset(this,a,e)});if(!b||!b.ownerDocument)return null;if(b===b.ownerDocument.body)return c.offset.bodyOffset(b);var d=b.getBoundingClientRect(),f=b.ownerDocument;b=f.body;f=f.documentElement;return{top:d.top+(self.pageYOffset||c.support.boxModel&&f.scrollTop||b.scrollTop)-(f.clientTop||b.clientTop||0),left:d.left+(self.pageXOffset||c.support.boxModel&&f.scrollLeft||b.scrollLeft)-(f.clientLeft||b.clientLeft||0)}}:function(a){var b=
|
||||
this[0];if(a)return this.each(function(r){c.offset.setOffset(this,a,r)});if(!b||!b.ownerDocument)return null;if(b===b.ownerDocument.body)return c.offset.bodyOffset(b);c.offset.initialize();var d=b.offsetParent,f=b,e=b.ownerDocument,j,i=e.documentElement,o=e.body;f=(e=e.defaultView)?e.getComputedStyle(b,null):b.currentStyle;for(var k=b.offsetTop,n=b.offsetLeft;(b=b.parentNode)&&b!==o&&b!==i;){if(c.offset.supportsFixedPosition&&f.position==="fixed")break;j=e?e.getComputedStyle(b,null):b.currentStyle;
|
||||
k-=b.scrollTop;n-=b.scrollLeft;if(b===d){k+=b.offsetTop;n+=b.offsetLeft;if(c.offset.doesNotAddBorder&&!(c.offset.doesAddBorderForTableAndCells&&/^t(able|d|h)$/i.test(b.nodeName))){k+=parseFloat(j.borderTopWidth)||0;n+=parseFloat(j.borderLeftWidth)||0}f=d;d=b.offsetParent}if(c.offset.subtractsBorderForOverflowNotVisible&&j.overflow!=="visible"){k+=parseFloat(j.borderTopWidth)||0;n+=parseFloat(j.borderLeftWidth)||0}f=j}if(f.position==="relative"||f.position==="static"){k+=o.offsetTop;n+=o.offsetLeft}if(c.offset.supportsFixedPosition&&
|
||||
f.position==="fixed"){k+=Math.max(i.scrollTop,o.scrollTop);n+=Math.max(i.scrollLeft,o.scrollLeft)}return{top:k,left:n}};c.offset={initialize:function(){var a=s.body,b=s.createElement("div"),d,f,e,j=parseFloat(c.curCSS(a,"marginTop",true))||0;c.extend(b.style,{position:"absolute",top:0,left:0,margin:0,border:0,width:"1px",height:"1px",visibility:"hidden"});b.innerHTML="<div style='position:absolute;top:0;left:0;margin:0;border:5px solid #000;padding:0;width:1px;height:1px;'><div></div></div><table style='position:absolute;top:0;left:0;margin:0;border:5px solid #000;padding:0;width:1px;height:1px;' cellpadding='0' cellspacing='0'><tr><td></td></tr></table>";
|
||||
a.insertBefore(b,a.firstChild);d=b.firstChild;f=d.firstChild;e=d.nextSibling.firstChild.firstChild;this.doesNotAddBorder=f.offsetTop!==5;this.doesAddBorderForTableAndCells=e.offsetTop===5;f.style.position="fixed";f.style.top="20px";this.supportsFixedPosition=f.offsetTop===20||f.offsetTop===15;f.style.position=f.style.top="";d.style.overflow="hidden";d.style.position="relative";this.subtractsBorderForOverflowNotVisible=f.offsetTop===-5;this.doesNotIncludeMarginInBodyOffset=a.offsetTop!==j;a.removeChild(b);
|
||||
c.offset.initialize=c.noop},bodyOffset:function(a){var b=a.offsetTop,d=a.offsetLeft;c.offset.initialize();if(c.offset.doesNotIncludeMarginInBodyOffset){b+=parseFloat(c.curCSS(a,"marginTop",true))||0;d+=parseFloat(c.curCSS(a,"marginLeft",true))||0}return{top:b,left:d}},setOffset:function(a,b,d){if(/static/.test(c.curCSS(a,"position")))a.style.position="relative";var f=c(a),e=f.offset(),j=parseInt(c.curCSS(a,"top",true),10)||0,i=parseInt(c.curCSS(a,"left",true),10)||0;if(c.isFunction(b))b=b.call(a,
|
||||
d,e);d={top:b.top-e.top+j,left:b.left-e.left+i};"using"in b?b.using.call(a,d):f.css(d)}};c.fn.extend({position:function(){if(!this[0])return null;var a=this[0],b=this.offsetParent(),d=this.offset(),f=/^body|html$/i.test(b[0].nodeName)?{top:0,left:0}:b.offset();d.top-=parseFloat(c.curCSS(a,"marginTop",true))||0;d.left-=parseFloat(c.curCSS(a,"marginLeft",true))||0;f.top+=parseFloat(c.curCSS(b[0],"borderTopWidth",true))||0;f.left+=parseFloat(c.curCSS(b[0],"borderLeftWidth",true))||0;return{top:d.top-
|
||||
f.top,left:d.left-f.left}},offsetParent:function(){return this.map(function(){for(var a=this.offsetParent||s.body;a&&!/^body|html$/i.test(a.nodeName)&&c.css(a,"position")==="static";)a=a.offsetParent;return a})}});c.each(["Left","Top"],function(a,b){var d="scroll"+b;c.fn[d]=function(f){var e=this[0],j;if(!e)return null;if(f!==w)return this.each(function(){if(j=wa(this))j.scrollTo(!a?f:c(j).scrollLeft(),a?f:c(j).scrollTop());else this[d]=f});else return(j=wa(e))?"pageXOffset"in j?j[a?"pageYOffset":
|
||||
"pageXOffset"]:c.support.boxModel&&j.document.documentElement[d]||j.document.body[d]:e[d]}});c.each(["Height","Width"],function(a,b){var d=b.toLowerCase();c.fn["inner"+b]=function(){return this[0]?c.css(this[0],d,false,"padding"):null};c.fn["outer"+b]=function(f){return this[0]?c.css(this[0],d,false,f?"margin":"border"):null};c.fn[d]=function(f){var e=this[0];if(!e)return f==null?null:this;if(c.isFunction(f))return this.each(function(j){var i=c(this);i[d](f.call(this,j,i[d]()))});return"scrollTo"in
|
||||
e&&e.document?e.document.compatMode==="CSS1Compat"&&e.document.documentElement["client"+b]||e.document.body["client"+b]:e.nodeType===9?Math.max(e.documentElement["client"+b],e.body["scroll"+b],e.documentElement["scroll"+b],e.body["offset"+b],e.documentElement["offset"+b]):f===w?c.css(e,d):this.css(d,typeof f==="string"?f:f+"px")}});A.jQuery=A.$=c})(window);
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 199 B |
Binary file not shown.
|
After Width: | Height: | Size: 199 B |
@ -0,0 +1,62 @@
|
||||
.highlight .hll { background-color: #ffffcc }
|
||||
.highlight { background: #eeffcc; }
|
||||
.highlight .c { color: #408090; font-style: italic } /* Comment */
|
||||
.highlight .err { border: 1px solid #FF0000 } /* Error */
|
||||
.highlight .k { color: #007020; font-weight: bold } /* Keyword */
|
||||
.highlight .o { color: #666666 } /* Operator */
|
||||
.highlight .cm { color: #408090; font-style: italic } /* Comment.Multiline */
|
||||
.highlight .cp { color: #007020 } /* Comment.Preproc */
|
||||
.highlight .c1 { color: #408090; font-style: italic } /* Comment.Single */
|
||||
.highlight .cs { color: #408090; background-color: #fff0f0 } /* Comment.Special */
|
||||
.highlight .gd { color: #A00000 } /* Generic.Deleted */
|
||||
.highlight .ge { font-style: italic } /* Generic.Emph */
|
||||
.highlight .gr { color: #FF0000 } /* Generic.Error */
|
||||
.highlight .gh { color: #000080; font-weight: bold } /* Generic.Heading */
|
||||
.highlight .gi { color: #00A000 } /* Generic.Inserted */
|
||||
.highlight .go { color: #303030 } /* Generic.Output */
|
||||
.highlight .gp { color: #c65d09; font-weight: bold } /* Generic.Prompt */
|
||||
.highlight .gs { font-weight: bold } /* Generic.Strong */
|
||||
.highlight .gu { color: #800080; font-weight: bold } /* Generic.Subheading */
|
||||
.highlight .gt { color: #0040D0 } /* Generic.Traceback */
|
||||
.highlight .kc { color: #007020; font-weight: bold } /* Keyword.Constant */
|
||||
.highlight .kd { color: #007020; font-weight: bold } /* Keyword.Declaration */
|
||||
.highlight .kn { color: #007020; font-weight: bold } /* Keyword.Namespace */
|
||||
.highlight .kp { color: #007020 } /* Keyword.Pseudo */
|
||||
.highlight .kr { color: #007020; font-weight: bold } /* Keyword.Reserved */
|
||||
.highlight .kt { color: #902000 } /* Keyword.Type */
|
||||
.highlight .m { color: #208050 } /* Literal.Number */
|
||||
.highlight .s { color: #4070a0 } /* Literal.String */
|
||||
.highlight .na { color: #4070a0 } /* Name.Attribute */
|
||||
.highlight .nb { color: #007020 } /* Name.Builtin */
|
||||
.highlight .nc { color: #0e84b5; font-weight: bold } /* Name.Class */
|
||||
.highlight .no { color: #60add5 } /* Name.Constant */
|
||||
.highlight .nd { color: #555555; font-weight: bold } /* Name.Decorator */
|
||||
.highlight .ni { color: #d55537; font-weight: bold } /* Name.Entity */
|
||||
.highlight .ne { color: #007020 } /* Name.Exception */
|
||||
.highlight .nf { color: #06287e } /* Name.Function */
|
||||
.highlight .nl { color: #002070; font-weight: bold } /* Name.Label */
|
||||
.highlight .nn { color: #0e84b5; font-weight: bold } /* Name.Namespace */
|
||||
.highlight .nt { color: #062873; font-weight: bold } /* Name.Tag */
|
||||
.highlight .nv { color: #bb60d5 } /* Name.Variable */
|
||||
.highlight .ow { color: #007020; font-weight: bold } /* Operator.Word */
|
||||
.highlight .w { color: #bbbbbb } /* Text.Whitespace */
|
||||
.highlight .mf { color: #208050 } /* Literal.Number.Float */
|
||||
.highlight .mh { color: #208050 } /* Literal.Number.Hex */
|
||||
.highlight .mi { color: #208050 } /* Literal.Number.Integer */
|
||||
.highlight .mo { color: #208050 } /* Literal.Number.Oct */
|
||||
.highlight .sb { color: #4070a0 } /* Literal.String.Backtick */
|
||||
.highlight .sc { color: #4070a0 } /* Literal.String.Char */
|
||||
.highlight .sd { color: #4070a0; font-style: italic } /* Literal.String.Doc */
|
||||
.highlight .s2 { color: #4070a0 } /* Literal.String.Double */
|
||||
.highlight .se { color: #4070a0; font-weight: bold } /* Literal.String.Escape */
|
||||
.highlight .sh { color: #4070a0 } /* Literal.String.Heredoc */
|
||||
.highlight .si { color: #70a0d0; font-style: italic } /* Literal.String.Interpol */
|
||||
.highlight .sx { color: #c65d09 } /* Literal.String.Other */
|
||||
.highlight .sr { color: #235388 } /* Literal.String.Regex */
|
||||
.highlight .s1 { color: #4070a0 } /* Literal.String.Single */
|
||||
.highlight .ss { color: #517918 } /* Literal.String.Symbol */
|
||||
.highlight .bp { color: #007020 } /* Name.Builtin.Pseudo */
|
||||
.highlight .vc { color: #bb60d5 } /* Name.Variable.Class */
|
||||
.highlight .vg { color: #bb60d5 } /* Name.Variable.Global */
|
||||
.highlight .vi { color: #bb60d5 } /* Name.Variable.Instance */
|
||||
.highlight .il { color: #208050 } /* Literal.Number.Integer.Long */
|
||||
@ -0,0 +1,560 @@
|
||||
/*
|
||||
* searchtools.js_t
|
||||
* ~~~~~~~~~~~~~~~~
|
||||
*
|
||||
* Sphinx JavaScript utilties for the full-text search.
|
||||
*
|
||||
* :copyright: Copyright 2007-2011 by the Sphinx team, see AUTHORS.
|
||||
* :license: BSD, see LICENSE for details.
|
||||
*
|
||||
*/
|
||||
|
||||
/**
|
||||
* helper function to return a node containing the
|
||||
* search summary for a given text. keywords is a list
|
||||
* of stemmed words, hlwords is the list of normal, unstemmed
|
||||
* words. the first one is used to find the occurance, the
|
||||
* latter for highlighting it.
|
||||
*/
|
||||
|
||||
jQuery.makeSearchSummary = function(text, keywords, hlwords) {
|
||||
var textLower = text.toLowerCase();
|
||||
var start = 0;
|
||||
$.each(keywords, function() {
|
||||
var i = textLower.indexOf(this.toLowerCase());
|
||||
if (i > -1)
|
||||
start = i;
|
||||
});
|
||||
start = Math.max(start - 120, 0);
|
||||
var excerpt = ((start > 0) ? '...' : '') +
|
||||
$.trim(text.substr(start, 240)) +
|
||||
((start + 240 - text.length) ? '...' : '');
|
||||
var rv = $('<div class="context"></div>').text(excerpt);
|
||||
$.each(hlwords, function() {
|
||||
rv = rv.highlightText(this, 'highlighted');
|
||||
});
|
||||
return rv;
|
||||
}
|
||||
|
||||
|
||||
/**
|
||||
* Porter Stemmer
|
||||
*/
|
||||
var Stemmer = function() {
|
||||
|
||||
var step2list = {
|
||||
ational: 'ate',
|
||||
tional: 'tion',
|
||||
enci: 'ence',
|
||||
anci: 'ance',
|
||||
izer: 'ize',
|
||||
bli: 'ble',
|
||||
alli: 'al',
|
||||
entli: 'ent',
|
||||
eli: 'e',
|
||||
ousli: 'ous',
|
||||
ization: 'ize',
|
||||
ation: 'ate',
|
||||
ator: 'ate',
|
||||
alism: 'al',
|
||||
iveness: 'ive',
|
||||
fulness: 'ful',
|
||||
ousness: 'ous',
|
||||
aliti: 'al',
|
||||
iviti: 'ive',
|
||||
biliti: 'ble',
|
||||
logi: 'log'
|
||||
};
|
||||
|
||||
var step3list = {
|
||||
icate: 'ic',
|
||||
ative: '',
|
||||
alize: 'al',
|
||||
iciti: 'ic',
|
||||
ical: 'ic',
|
||||
ful: '',
|
||||
ness: ''
|
||||
};
|
||||
|
||||
var c = "[^aeiou]"; // consonant
|
||||
var v = "[aeiouy]"; // vowel
|
||||
var C = c + "[^aeiouy]*"; // consonant sequence
|
||||
var V = v + "[aeiou]*"; // vowel sequence
|
||||
|
||||
var mgr0 = "^(" + C + ")?" + V + C; // [C]VC... is m>0
|
||||
var meq1 = "^(" + C + ")?" + V + C + "(" + V + ")?$"; // [C]VC[V] is m=1
|
||||
var mgr1 = "^(" + C + ")?" + V + C + V + C; // [C]VCVC... is m>1
|
||||
var s_v = "^(" + C + ")?" + v; // vowel in stem
|
||||
|
||||
this.stemWord = function (w) {
|
||||
var stem;
|
||||
var suffix;
|
||||
var firstch;
|
||||
var origword = w;
|
||||
|
||||
if (w.length < 3)
|
||||
return w;
|
||||
|
||||
var re;
|
||||
var re2;
|
||||
var re3;
|
||||
var re4;
|
||||
|
||||
firstch = w.substr(0,1);
|
||||
if (firstch == "y")
|
||||
w = firstch.toUpperCase() + w.substr(1);
|
||||
|
||||
// Step 1a
|
||||
re = /^(.+?)(ss|i)es$/;
|
||||
re2 = /^(.+?)([^s])s$/;
|
||||
|
||||
if (re.test(w))
|
||||
w = w.replace(re,"$1$2");
|
||||
else if (re2.test(w))
|
||||
w = w.replace(re2,"$1$2");
|
||||
|
||||
// Step 1b
|
||||
re = /^(.+?)eed$/;
|
||||
re2 = /^(.+?)(ed|ing)$/;
|
||||
if (re.test(w)) {
|
||||
var fp = re.exec(w);
|
||||
re = new RegExp(mgr0);
|
||||
if (re.test(fp[1])) {
|
||||
re = /.$/;
|
||||
w = w.replace(re,"");
|
||||
}
|
||||
}
|
||||
else if (re2.test(w)) {
|
||||
var fp = re2.exec(w);
|
||||
stem = fp[1];
|
||||
re2 = new RegExp(s_v);
|
||||
if (re2.test(stem)) {
|
||||
w = stem;
|
||||
re2 = /(at|bl|iz)$/;
|
||||
re3 = new RegExp("([^aeiouylsz])\\1$");
|
||||
re4 = new RegExp("^" + C + v + "[^aeiouwxy]$");
|
||||
if (re2.test(w))
|
||||
w = w + "e";
|
||||
else if (re3.test(w)) {
|
||||
re = /.$/;
|
||||
w = w.replace(re,"");
|
||||
}
|
||||
else if (re4.test(w))
|
||||
w = w + "e";
|
||||
}
|
||||
}
|
||||
|
||||
// Step 1c
|
||||
re = /^(.+?)y$/;
|
||||
if (re.test(w)) {
|
||||
var fp = re.exec(w);
|
||||
stem = fp[1];
|
||||
re = new RegExp(s_v);
|
||||
if (re.test(stem))
|
||||
w = stem + "i";
|
||||
}
|
||||
|
||||
// Step 2
|
||||
re = /^(.+?)(ational|tional|enci|anci|izer|bli|alli|entli|eli|ousli|ization|ation|ator|alism|iveness|fulness|ousness|aliti|iviti|biliti|logi)$/;
|
||||
if (re.test(w)) {
|
||||
var fp = re.exec(w);
|
||||
stem = fp[1];
|
||||
suffix = fp[2];
|
||||
re = new RegExp(mgr0);
|
||||
if (re.test(stem))
|
||||
w = stem + step2list[suffix];
|
||||
}
|
||||
|
||||
// Step 3
|
||||
re = /^(.+?)(icate|ative|alize|iciti|ical|ful|ness)$/;
|
||||
if (re.test(w)) {
|
||||
var fp = re.exec(w);
|
||||
stem = fp[1];
|
||||
suffix = fp[2];
|
||||
re = new RegExp(mgr0);
|
||||
if (re.test(stem))
|
||||
w = stem + step3list[suffix];
|
||||
}
|
||||
|
||||
// Step 4
|
||||
re = /^(.+?)(al|ance|ence|er|ic|able|ible|ant|ement|ment|ent|ou|ism|ate|iti|ous|ive|ize)$/;
|
||||
re2 = /^(.+?)(s|t)(ion)$/;
|
||||
if (re.test(w)) {
|
||||
var fp = re.exec(w);
|
||||
stem = fp[1];
|
||||
re = new RegExp(mgr1);
|
||||
if (re.test(stem))
|
||||
w = stem;
|
||||
}
|
||||
else if (re2.test(w)) {
|
||||
var fp = re2.exec(w);
|
||||
stem = fp[1] + fp[2];
|
||||
re2 = new RegExp(mgr1);
|
||||
if (re2.test(stem))
|
||||
w = stem;
|
||||
}
|
||||
|
||||
// Step 5
|
||||
re = /^(.+?)e$/;
|
||||
if (re.test(w)) {
|
||||
var fp = re.exec(w);
|
||||
stem = fp[1];
|
||||
re = new RegExp(mgr1);
|
||||
re2 = new RegExp(meq1);
|
||||
re3 = new RegExp("^" + C + v + "[^aeiouwxy]$");
|
||||
if (re.test(stem) || (re2.test(stem) && !(re3.test(stem))))
|
||||
w = stem;
|
||||
}
|
||||
re = /ll$/;
|
||||
re2 = new RegExp(mgr1);
|
||||
if (re.test(w) && re2.test(w)) {
|
||||
re = /.$/;
|
||||
w = w.replace(re,"");
|
||||
}
|
||||
|
||||
// and turn initial Y back to y
|
||||
if (firstch == "y")
|
||||
w = firstch.toLowerCase() + w.substr(1);
|
||||
return w;
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
/**
|
||||
* Search Module
|
||||
*/
|
||||
var Search = {
|
||||
|
||||
_index : null,
|
||||
_queued_query : null,
|
||||
_pulse_status : -1,
|
||||
|
||||
init : function() {
|
||||
var params = $.getQueryParameters();
|
||||
if (params.q) {
|
||||
var query = params.q[0];
|
||||
$('input[name="q"]')[0].value = query;
|
||||
this.performSearch(query);
|
||||
}
|
||||
},
|
||||
|
||||
loadIndex : function(url) {
|
||||
$.ajax({type: "GET", url: url, data: null, success: null,
|
||||
dataType: "script", cache: true});
|
||||
},
|
||||
|
||||
setIndex : function(index) {
|
||||
var q;
|
||||
this._index = index;
|
||||
if ((q = this._queued_query) !== null) {
|
||||
this._queued_query = null;
|
||||
Search.query(q);
|
||||
}
|
||||
},
|
||||
|
||||
hasIndex : function() {
|
||||
return this._index !== null;
|
||||
},
|
||||
|
||||
deferQuery : function(query) {
|
||||
this._queued_query = query;
|
||||
},
|
||||
|
||||
stopPulse : function() {
|
||||
this._pulse_status = 0;
|
||||
},
|
||||
|
||||
startPulse : function() {
|
||||
if (this._pulse_status >= 0)
|
||||
return;
|
||||
function pulse() {
|
||||
Search._pulse_status = (Search._pulse_status + 1) % 4;
|
||||
var dotString = '';
|
||||
for (var i = 0; i < Search._pulse_status; i++)
|
||||
dotString += '.';
|
||||
Search.dots.text(dotString);
|
||||
if (Search._pulse_status > -1)
|
||||
window.setTimeout(pulse, 500);
|
||||
};
|
||||
pulse();
|
||||
},
|
||||
|
||||
/**
|
||||
* perform a search for something
|
||||
*/
|
||||
performSearch : function(query) {
|
||||
// create the required interface elements
|
||||
this.out = $('#search-results');
|
||||
this.title = $('<h2>' + _('Searching') + '</h2>').appendTo(this.out);
|
||||
this.dots = $('<span></span>').appendTo(this.title);
|
||||
this.status = $('<p style="display: none"></p>').appendTo(this.out);
|
||||
this.output = $('<ul class="search"/>').appendTo(this.out);
|
||||
|
||||
$('#search-progress').text(_('Preparing search...'));
|
||||
this.startPulse();
|
||||
|
||||
// index already loaded, the browser was quick!
|
||||
if (this.hasIndex())
|
||||
this.query(query);
|
||||
else
|
||||
this.deferQuery(query);
|
||||
},
|
||||
|
||||
query : function(query) {
|
||||
var stopwords = ["and","then","into","it","as","are","in","if","for","no","there","their","was","is","be","to","that","but","they","not","such","with","by","a","on","these","of","will","this","near","the","or","at"];
|
||||
|
||||
// Stem the searchterms and add them to the correct list
|
||||
var stemmer = new Stemmer();
|
||||
var searchterms = [];
|
||||
var excluded = [];
|
||||
var hlterms = [];
|
||||
var tmp = query.split(/\s+/);
|
||||
var objectterms = [];
|
||||
for (var i = 0; i < tmp.length; i++) {
|
||||
if (tmp[i] != "") {
|
||||
objectterms.push(tmp[i].toLowerCase());
|
||||
}
|
||||
|
||||
if ($u.indexOf(stopwords, tmp[i]) != -1 || tmp[i].match(/^\d+$/) ||
|
||||
tmp[i] == "") {
|
||||
// skip this "word"
|
||||
continue;
|
||||
}
|
||||
// stem the word
|
||||
var word = stemmer.stemWord(tmp[i]).toLowerCase();
|
||||
// select the correct list
|
||||
if (word[0] == '-') {
|
||||
var toAppend = excluded;
|
||||
word = word.substr(1);
|
||||
}
|
||||
else {
|
||||
var toAppend = searchterms;
|
||||
hlterms.push(tmp[i].toLowerCase());
|
||||
}
|
||||
// only add if not already in the list
|
||||
if (!$.contains(toAppend, word))
|
||||
toAppend.push(word);
|
||||
};
|
||||
var highlightstring = '?highlight=' + $.urlencode(hlterms.join(" "));
|
||||
|
||||
// console.debug('SEARCH: searching for:');
|
||||
// console.info('required: ', searchterms);
|
||||
// console.info('excluded: ', excluded);
|
||||
|
||||
// prepare search
|
||||
var filenames = this._index.filenames;
|
||||
var titles = this._index.titles;
|
||||
var terms = this._index.terms;
|
||||
var fileMap = {};
|
||||
var files = null;
|
||||
// different result priorities
|
||||
var importantResults = [];
|
||||
var objectResults = [];
|
||||
var regularResults = [];
|
||||
var unimportantResults = [];
|
||||
$('#search-progress').empty();
|
||||
|
||||
// lookup as object
|
||||
for (var i = 0; i < objectterms.length; i++) {
|
||||
var others = [].concat(objectterms.slice(0,i),
|
||||
objectterms.slice(i+1, objectterms.length))
|
||||
var results = this.performObjectSearch(objectterms[i], others);
|
||||
// Assume first word is most likely to be the object,
|
||||
// other words more likely to be in description.
|
||||
// Therefore put matches for earlier words first.
|
||||
// (Results are eventually used in reverse order).
|
||||
objectResults = results[0].concat(objectResults);
|
||||
importantResults = results[1].concat(importantResults);
|
||||
unimportantResults = results[2].concat(unimportantResults);
|
||||
}
|
||||
|
||||
// perform the search on the required terms
|
||||
for (var i = 0; i < searchterms.length; i++) {
|
||||
var word = searchterms[i];
|
||||
// no match but word was a required one
|
||||
if ((files = terms[word]) == null)
|
||||
break;
|
||||
if (files.length == undefined) {
|
||||
files = [files];
|
||||
}
|
||||
// create the mapping
|
||||
for (var j = 0; j < files.length; j++) {
|
||||
var file = files[j];
|
||||
if (file in fileMap)
|
||||
fileMap[file].push(word);
|
||||
else
|
||||
fileMap[file] = [word];
|
||||
}
|
||||
}
|
||||
|
||||
// now check if the files don't contain excluded terms
|
||||
for (var file in fileMap) {
|
||||
var valid = true;
|
||||
|
||||
// check if all requirements are matched
|
||||
if (fileMap[file].length != searchterms.length)
|
||||
continue;
|
||||
|
||||
// ensure that none of the excluded terms is in the
|
||||
// search result.
|
||||
for (var i = 0; i < excluded.length; i++) {
|
||||
if (terms[excluded[i]] == file ||
|
||||
$.contains(terms[excluded[i]] || [], file)) {
|
||||
valid = false;
|
||||
break;
|
||||
}
|
||||
}
|
||||
|
||||
// if we have still a valid result we can add it
|
||||
// to the result list
|
||||
if (valid)
|
||||
regularResults.push([filenames[file], titles[file], '', null]);
|
||||
}
|
||||
|
||||
// delete unused variables in order to not waste
|
||||
// memory until list is retrieved completely
|
||||
delete filenames, titles, terms;
|
||||
|
||||
// now sort the regular results descending by title
|
||||
regularResults.sort(function(a, b) {
|
||||
var left = a[1].toLowerCase();
|
||||
var right = b[1].toLowerCase();
|
||||
return (left > right) ? -1 : ((left < right) ? 1 : 0);
|
||||
});
|
||||
|
||||
// combine all results
|
||||
var results = unimportantResults.concat(regularResults)
|
||||
.concat(objectResults).concat(importantResults);
|
||||
|
||||
// print the results
|
||||
var resultCount = results.length;
|
||||
function displayNextItem() {
|
||||
// results left, load the summary and display it
|
||||
if (results.length) {
|
||||
var item = results.pop();
|
||||
var listItem = $('<li style="display:none"></li>');
|
||||
if (DOCUMENTATION_OPTIONS.FILE_SUFFIX == '') {
|
||||
// dirhtml builder
|
||||
var dirname = item[0] + '/';
|
||||
if (dirname.match(/\/index\/$/)) {
|
||||
dirname = dirname.substring(0, dirname.length-6);
|
||||
} else if (dirname == 'index/') {
|
||||
dirname = '';
|
||||
}
|
||||
listItem.append($('<a/>').attr('href',
|
||||
DOCUMENTATION_OPTIONS.URL_ROOT + dirname +
|
||||
highlightstring + item[2]).html(item[1]));
|
||||
} else {
|
||||
// normal html builders
|
||||
listItem.append($('<a/>').attr('href',
|
||||
item[0] + DOCUMENTATION_OPTIONS.FILE_SUFFIX +
|
||||
highlightstring + item[2]).html(item[1]));
|
||||
}
|
||||
if (item[3]) {
|
||||
listItem.append($('<span> (' + item[3] + ')</span>'));
|
||||
Search.output.append(listItem);
|
||||
listItem.slideDown(5, function() {
|
||||
displayNextItem();
|
||||
});
|
||||
} else if (DOCUMENTATION_OPTIONS.HAS_SOURCE) {
|
||||
$.get(DOCUMENTATION_OPTIONS.URL_ROOT + '_sources/' +
|
||||
item[0] + '.txt', function(data) {
|
||||
if (data != '') {
|
||||
listItem.append($.makeSearchSummary(data, searchterms, hlterms));
|
||||
Search.output.append(listItem);
|
||||
}
|
||||
listItem.slideDown(5, function() {
|
||||
displayNextItem();
|
||||
});
|
||||
}, "text");
|
||||
} else {
|
||||
// no source available, just display title
|
||||
Search.output.append(listItem);
|
||||
listItem.slideDown(5, function() {
|
||||
displayNextItem();
|
||||
});
|
||||
}
|
||||
}
|
||||
// search finished, update title and status message
|
||||
else {
|
||||
Search.stopPulse();
|
||||
Search.title.text(_('Search Results'));
|
||||
if (!resultCount)
|
||||
Search.status.text(_('Your search did not match any documents. Please make sure that all words are spelled correctly and that you\'ve selected enough categories.'));
|
||||
else
|
||||
Search.status.text(_('Search finished, found %s page(s) matching the search query.').replace('%s', resultCount));
|
||||
Search.status.fadeIn(500);
|
||||
}
|
||||
}
|
||||
displayNextItem();
|
||||
},
|
||||
|
||||
performObjectSearch : function(object, otherterms) {
|
||||
var filenames = this._index.filenames;
|
||||
var objects = this._index.objects;
|
||||
var objnames = this._index.objnames;
|
||||
var titles = this._index.titles;
|
||||
|
||||
var importantResults = [];
|
||||
var objectResults = [];
|
||||
var unimportantResults = [];
|
||||
|
||||
for (var prefix in objects) {
|
||||
for (var name in objects[prefix]) {
|
||||
var fullname = (prefix ? prefix + '.' : '') + name;
|
||||
if (fullname.toLowerCase().indexOf(object) > -1) {
|
||||
var match = objects[prefix][name];
|
||||
var objname = objnames[match[1]][2];
|
||||
var title = titles[match[0]];
|
||||
// If more than one term searched for, we require other words to be
|
||||
// found in the name/title/description
|
||||
if (otherterms.length > 0) {
|
||||
var haystack = (prefix + ' ' + name + ' ' +
|
||||
objname + ' ' + title).toLowerCase();
|
||||
var allfound = true;
|
||||
for (var i = 0; i < otherterms.length; i++) {
|
||||
if (haystack.indexOf(otherterms[i]) == -1) {
|
||||
allfound = false;
|
||||
break;
|
||||
}
|
||||
}
|
||||
if (!allfound) {
|
||||
continue;
|
||||
}
|
||||
}
|
||||
var descr = objname + _(', in ') + title;
|
||||
anchor = match[3];
|
||||
if (anchor == '')
|
||||
anchor = fullname;
|
||||
else if (anchor == '-')
|
||||
anchor = objnames[match[1]][1] + '-' + fullname;
|
||||
result = [filenames[match[0]], fullname, '#'+anchor, descr];
|
||||
switch (match[2]) {
|
||||
case 1: objectResults.push(result); break;
|
||||
case 0: importantResults.push(result); break;
|
||||
case 2: unimportantResults.push(result); break;
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// sort results descending
|
||||
objectResults.sort(function(a, b) {
|
||||
return (a[1] > b[1]) ? -1 : ((a[1] < b[1]) ? 1 : 0);
|
||||
});
|
||||
|
||||
importantResults.sort(function(a, b) {
|
||||
return (a[1] > b[1]) ? -1 : ((a[1] < b[1]) ? 1 : 0);
|
||||
});
|
||||
|
||||
unimportantResults.sort(function(a, b) {
|
||||
return (a[1] > b[1]) ? -1 : ((a[1] < b[1]) ? 1 : 0);
|
||||
});
|
||||
|
||||
return [importantResults, objectResults, unimportantResults]
|
||||
}
|
||||
}
|
||||
|
||||
$(document).ready(function() {
|
||||
Search.init();
|
||||
});
|
||||
@ -0,0 +1,148 @@
|
||||
/*
|
||||
* sidebar.js
|
||||
* ~~~~~~~~~~
|
||||
*
|
||||
* This script makes the Sphinx sidebar collapsible.
|
||||
*
|
||||
* .sphinxsidebar contains .sphinxsidebarwrapper. This script adds
|
||||
* in .sphixsidebar, after .sphinxsidebarwrapper, the #sidebarbutton
|
||||
* used to collapse and expand the sidebar.
|
||||
*
|
||||
* When the sidebar is collapsed the .sphinxsidebarwrapper is hidden
|
||||
* and the width of the sidebar and the margin-left of the document
|
||||
* are decreased. When the sidebar is expanded the opposite happens.
|
||||
* This script saves a per-browser/per-session cookie used to
|
||||
* remember the position of the sidebar among the pages.
|
||||
* Once the browser is closed the cookie is deleted and the position
|
||||
* reset to the default (expanded).
|
||||
*
|
||||
* :copyright: Copyright 2007-2011 by the Sphinx team, see AUTHORS.
|
||||
* :license: BSD, see LICENSE for details.
|
||||
*
|
||||
*/
|
||||
|
||||
$(function() {
|
||||
// global elements used by the functions.
|
||||
// the 'sidebarbutton' element is defined as global after its
|
||||
// creation, in the add_sidebar_button function
|
||||
var bodywrapper = $('.bodywrapper');
|
||||
var sidebar = $('.sphinxsidebar');
|
||||
var sidebarwrapper = $('.sphinxsidebarwrapper');
|
||||
|
||||
// original margin-left of the bodywrapper and width of the sidebar
|
||||
// with the sidebar expanded
|
||||
var bw_margin_expanded = bodywrapper.css('margin-left');
|
||||
var ssb_width_expanded = sidebar.width();
|
||||
|
||||
// margin-left of the bodywrapper and width of the sidebar
|
||||
// with the sidebar collapsed
|
||||
var bw_margin_collapsed = '.8em';
|
||||
var ssb_width_collapsed = '.8em';
|
||||
|
||||
// colors used by the current theme
|
||||
var dark_color = $('.related').css('background-color');
|
||||
var light_color = $('.document').css('background-color');
|
||||
|
||||
function sidebar_is_collapsed() {
|
||||
return sidebarwrapper.is(':not(:visible)');
|
||||
}
|
||||
|
||||
function toggle_sidebar() {
|
||||
if (sidebar_is_collapsed())
|
||||
expand_sidebar();
|
||||
else
|
||||
collapse_sidebar();
|
||||
}
|
||||
|
||||
function collapse_sidebar() {
|
||||
sidebarwrapper.hide();
|
||||
sidebar.css('width', ssb_width_collapsed);
|
||||
bodywrapper.css('margin-left', bw_margin_collapsed);
|
||||
sidebarbutton.css({
|
||||
'margin-left': '0',
|
||||
'height': bodywrapper.height()
|
||||
});
|
||||
sidebarbutton.find('span').text('»');
|
||||
sidebarbutton.attr('title', _('Expand sidebar'));
|
||||
document.cookie = 'sidebar=collapsed';
|
||||
}
|
||||
|
||||
function expand_sidebar() {
|
||||
bodywrapper.css('margin-left', bw_margin_expanded);
|
||||
sidebar.css('width', ssb_width_expanded);
|
||||
sidebarwrapper.show();
|
||||
sidebarbutton.css({
|
||||
'margin-left': ssb_width_expanded-12,
|
||||
'height': bodywrapper.height()
|
||||
});
|
||||
sidebarbutton.find('span').text('«');
|
||||
sidebarbutton.attr('title', _('Collapse sidebar'));
|
||||
document.cookie = 'sidebar=expanded';
|
||||
}
|
||||
|
||||
function add_sidebar_button() {
|
||||
sidebarwrapper.css({
|
||||
'float': 'left',
|
||||
'margin-right': '0',
|
||||
'width': ssb_width_expanded - 28
|
||||
});
|
||||
// create the button
|
||||
sidebar.append(
|
||||
'<div id="sidebarbutton"><span>«</span></div>'
|
||||
);
|
||||
var sidebarbutton = $('#sidebarbutton');
|
||||
light_color = sidebarbutton.css('background-color');
|
||||
// find the height of the viewport to center the '<<' in the page
|
||||
var viewport_height;
|
||||
if (window.innerHeight)
|
||||
viewport_height = window.innerHeight;
|
||||
else
|
||||
viewport_height = $(window).height();
|
||||
sidebarbutton.find('span').css({
|
||||
'display': 'block',
|
||||
'margin-top': (viewport_height - sidebar.position().top - 20) / 2
|
||||
});
|
||||
|
||||
sidebarbutton.click(toggle_sidebar);
|
||||
sidebarbutton.attr('title', _('Collapse sidebar'));
|
||||
sidebarbutton.css({
|
||||
'color': '#FFFFFF',
|
||||
'border-left': '1px solid ' + dark_color,
|
||||
'font-size': '1.2em',
|
||||
'cursor': 'pointer',
|
||||
'height': bodywrapper.height(),
|
||||
'padding-top': '1px',
|
||||
'margin-left': ssb_width_expanded - 12
|
||||
});
|
||||
|
||||
sidebarbutton.hover(
|
||||
function () {
|
||||
$(this).css('background-color', dark_color);
|
||||
},
|
||||
function () {
|
||||
$(this).css('background-color', light_color);
|
||||
}
|
||||
);
|
||||
}
|
||||
|
||||
function set_position_from_cookie() {
|
||||
if (!document.cookie)
|
||||
return;
|
||||
var items = document.cookie.split(';');
|
||||
for(var k=0; k<items.length; k++) {
|
||||
var key_val = items[k].split('=');
|
||||
var key = key_val[0];
|
||||
if (key == 'sidebar') {
|
||||
var value = key_val[1];
|
||||
if ((value == 'collapsed') && (!sidebar_is_collapsed()))
|
||||
collapse_sidebar();
|
||||
else if ((value == 'expanded') && (sidebar_is_collapsed()))
|
||||
expand_sidebar();
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
add_sidebar_button();
|
||||
var sidebarbutton = $('#sidebarbutton');
|
||||
set_position_from_cookie();
|
||||
});
|
||||
@ -0,0 +1,23 @@
|
||||
// Underscore.js 0.5.5
|
||||
// (c) 2009 Jeremy Ashkenas, DocumentCloud Inc.
|
||||
// Underscore is freely distributable under the terms of the MIT license.
|
||||
// Portions of Underscore are inspired by or borrowed from Prototype.js,
|
||||
// Oliver Steele's Functional, and John Resig's Micro-Templating.
|
||||
// For all details and documentation:
|
||||
// http://documentcloud.github.com/underscore/
|
||||
(function(){var j=this,n=j._,i=function(a){this._wrapped=a},m=typeof StopIteration!=="undefined"?StopIteration:"__break__",b=j._=function(a){return new i(a)};if(typeof exports!=="undefined")exports._=b;var k=Array.prototype.slice,o=Array.prototype.unshift,p=Object.prototype.toString,q=Object.prototype.hasOwnProperty,r=Object.prototype.propertyIsEnumerable;b.VERSION="0.5.5";b.each=function(a,c,d){try{if(a.forEach)a.forEach(c,d);else if(b.isArray(a)||b.isArguments(a))for(var e=0,f=a.length;e<f;e++)c.call(d,
|
||||
a[e],e,a);else{var g=b.keys(a);f=g.length;for(e=0;e<f;e++)c.call(d,a[g[e]],g[e],a)}}catch(h){if(h!=m)throw h;}return a};b.map=function(a,c,d){if(a&&b.isFunction(a.map))return a.map(c,d);var e=[];b.each(a,function(f,g,h){e.push(c.call(d,f,g,h))});return e};b.reduce=function(a,c,d,e){if(a&&b.isFunction(a.reduce))return a.reduce(b.bind(d,e),c);b.each(a,function(f,g,h){c=d.call(e,c,f,g,h)});return c};b.reduceRight=function(a,c,d,e){if(a&&b.isFunction(a.reduceRight))return a.reduceRight(b.bind(d,e),c);
|
||||
var f=b.clone(b.toArray(a)).reverse();b.each(f,function(g,h){c=d.call(e,c,g,h,a)});return c};b.detect=function(a,c,d){var e;b.each(a,function(f,g,h){if(c.call(d,f,g,h)){e=f;b.breakLoop()}});return e};b.select=function(a,c,d){if(a&&b.isFunction(a.filter))return a.filter(c,d);var e=[];b.each(a,function(f,g,h){c.call(d,f,g,h)&&e.push(f)});return e};b.reject=function(a,c,d){var e=[];b.each(a,function(f,g,h){!c.call(d,f,g,h)&&e.push(f)});return e};b.all=function(a,c,d){c=c||b.identity;if(a&&b.isFunction(a.every))return a.every(c,
|
||||
d);var e=true;b.each(a,function(f,g,h){(e=e&&c.call(d,f,g,h))||b.breakLoop()});return e};b.any=function(a,c,d){c=c||b.identity;if(a&&b.isFunction(a.some))return a.some(c,d);var e=false;b.each(a,function(f,g,h){if(e=c.call(d,f,g,h))b.breakLoop()});return e};b.include=function(a,c){if(b.isArray(a))return b.indexOf(a,c)!=-1;var d=false;b.each(a,function(e){if(d=e===c)b.breakLoop()});return d};b.invoke=function(a,c){var d=b.rest(arguments,2);return b.map(a,function(e){return(c?e[c]:e).apply(e,d)})};b.pluck=
|
||||
function(a,c){return b.map(a,function(d){return d[c]})};b.max=function(a,c,d){if(!c&&b.isArray(a))return Math.max.apply(Math,a);var e={computed:-Infinity};b.each(a,function(f,g,h){g=c?c.call(d,f,g,h):f;g>=e.computed&&(e={value:f,computed:g})});return e.value};b.min=function(a,c,d){if(!c&&b.isArray(a))return Math.min.apply(Math,a);var e={computed:Infinity};b.each(a,function(f,g,h){g=c?c.call(d,f,g,h):f;g<e.computed&&(e={value:f,computed:g})});return e.value};b.sortBy=function(a,c,d){return b.pluck(b.map(a,
|
||||
function(e,f,g){return{value:e,criteria:c.call(d,e,f,g)}}).sort(function(e,f){e=e.criteria;f=f.criteria;return e<f?-1:e>f?1:0}),"value")};b.sortedIndex=function(a,c,d){d=d||b.identity;for(var e=0,f=a.length;e<f;){var g=e+f>>1;d(a[g])<d(c)?(e=g+1):(f=g)}return e};b.toArray=function(a){if(!a)return[];if(a.toArray)return a.toArray();if(b.isArray(a))return a;if(b.isArguments(a))return k.call(a);return b.values(a)};b.size=function(a){return b.toArray(a).length};b.first=function(a,c,d){return c&&!d?k.call(a,
|
||||
0,c):a[0]};b.rest=function(a,c,d){return k.call(a,b.isUndefined(c)||d?1:c)};b.last=function(a){return a[a.length-1]};b.compact=function(a){return b.select(a,function(c){return!!c})};b.flatten=function(a){return b.reduce(a,[],function(c,d){if(b.isArray(d))return c.concat(b.flatten(d));c.push(d);return c})};b.without=function(a){var c=b.rest(arguments);return b.select(a,function(d){return!b.include(c,d)})};b.uniq=function(a,c){return b.reduce(a,[],function(d,e,f){if(0==f||(c===true?b.last(d)!=e:!b.include(d,
|
||||
e)))d.push(e);return d})};b.intersect=function(a){var c=b.rest(arguments);return b.select(b.uniq(a),function(d){return b.all(c,function(e){return b.indexOf(e,d)>=0})})};b.zip=function(){for(var a=b.toArray(arguments),c=b.max(b.pluck(a,"length")),d=new Array(c),e=0;e<c;e++)d[e]=b.pluck(a,String(e));return d};b.indexOf=function(a,c){if(a.indexOf)return a.indexOf(c);for(var d=0,e=a.length;d<e;d++)if(a[d]===c)return d;return-1};b.lastIndexOf=function(a,c){if(a.lastIndexOf)return a.lastIndexOf(c);for(var d=
|
||||
a.length;d--;)if(a[d]===c)return d;return-1};b.range=function(a,c,d){var e=b.toArray(arguments),f=e.length<=1;a=f?0:e[0];c=f?e[0]:e[1];d=e[2]||1;e=Math.ceil((c-a)/d);if(e<=0)return[];e=new Array(e);f=a;for(var g=0;1;f+=d){if((d>0?f-c:c-f)>=0)return e;e[g++]=f}};b.bind=function(a,c){var d=b.rest(arguments,2);return function(){return a.apply(c||j,d.concat(b.toArray(arguments)))}};b.bindAll=function(a){var c=b.rest(arguments);if(c.length==0)c=b.functions(a);b.each(c,function(d){a[d]=b.bind(a[d],a)});
|
||||
return a};b.delay=function(a,c){var d=b.rest(arguments,2);return setTimeout(function(){return a.apply(a,d)},c)};b.defer=function(a){return b.delay.apply(b,[a,1].concat(b.rest(arguments)))};b.wrap=function(a,c){return function(){var d=[a].concat(b.toArray(arguments));return c.apply(c,d)}};b.compose=function(){var a=b.toArray(arguments);return function(){for(var c=b.toArray(arguments),d=a.length-1;d>=0;d--)c=[a[d].apply(this,c)];return c[0]}};b.keys=function(a){if(b.isArray(a))return b.range(0,a.length);
|
||||
var c=[];for(var d in a)q.call(a,d)&&c.push(d);return c};b.values=function(a){return b.map(a,b.identity)};b.functions=function(a){return b.select(b.keys(a),function(c){return b.isFunction(a[c])}).sort()};b.extend=function(a,c){for(var d in c)a[d]=c[d];return a};b.clone=function(a){if(b.isArray(a))return a.slice(0);return b.extend({},a)};b.tap=function(a,c){c(a);return a};b.isEqual=function(a,c){if(a===c)return true;var d=typeof a;if(d!=typeof c)return false;if(a==c)return true;if(!a&&c||a&&!c)return false;
|
||||
if(a.isEqual)return a.isEqual(c);if(b.isDate(a)&&b.isDate(c))return a.getTime()===c.getTime();if(b.isNaN(a)&&b.isNaN(c))return true;if(b.isRegExp(a)&&b.isRegExp(c))return a.source===c.source&&a.global===c.global&&a.ignoreCase===c.ignoreCase&&a.multiline===c.multiline;if(d!=="object")return false;if(a.length&&a.length!==c.length)return false;d=b.keys(a);var e=b.keys(c);if(d.length!=e.length)return false;for(var f in a)if(!b.isEqual(a[f],c[f]))return false;return true};b.isEmpty=function(a){return b.keys(a).length==
|
||||
0};b.isElement=function(a){return!!(a&&a.nodeType==1)};b.isArray=function(a){return!!(a&&a.concat&&a.unshift)};b.isArguments=function(a){return a&&b.isNumber(a.length)&&!b.isArray(a)&&!r.call(a,"length")};b.isFunction=function(a){return!!(a&&a.constructor&&a.call&&a.apply)};b.isString=function(a){return!!(a===""||a&&a.charCodeAt&&a.substr)};b.isNumber=function(a){return p.call(a)==="[object Number]"};b.isDate=function(a){return!!(a&&a.getTimezoneOffset&&a.setUTCFullYear)};b.isRegExp=function(a){return!!(a&&
|
||||
a.test&&a.exec&&(a.ignoreCase||a.ignoreCase===false))};b.isNaN=function(a){return b.isNumber(a)&&isNaN(a)};b.isNull=function(a){return a===null};b.isUndefined=function(a){return typeof a=="undefined"};b.noConflict=function(){j._=n;return this};b.identity=function(a){return a};b.breakLoop=function(){throw m;};var s=0;b.uniqueId=function(a){var c=s++;return a?a+c:c};b.template=function(a,c){a=new Function("obj","var p=[],print=function(){p.push.apply(p,arguments);};with(obj){p.push('"+a.replace(/[\r\t\n]/g,
|
||||
" ").replace(/'(?=[^%]*%>)/g,"\t").split("'").join("\\'").split("\t").join("'").replace(/<%=(.+?)%>/g,"',$1,'").split("<%").join("');").split("%>").join("p.push('")+"');}return p.join('');");return c?a(c):a};b.forEach=b.each;b.foldl=b.inject=b.reduce;b.foldr=b.reduceRight;b.filter=b.select;b.every=b.all;b.some=b.any;b.head=b.first;b.tail=b.rest;b.methods=b.functions;var l=function(a,c){return c?b(a).chain():a};b.each(b.functions(b),function(a){var c=b[a];i.prototype[a]=function(){var d=b.toArray(arguments);
|
||||
o.call(d,this._wrapped);return l(c.apply(b,d),this._chain)}});b.each(["pop","push","reverse","shift","sort","splice","unshift"],function(a){var c=Array.prototype[a];i.prototype[a]=function(){c.apply(this._wrapped,arguments);return l(this._wrapped,this._chain)}});b.each(["concat","join","slice"],function(a){var c=Array.prototype[a];i.prototype[a]=function(){return l(c.apply(this._wrapped,arguments),this._chain)}});i.prototype.chain=function(){this._chain=true;return this};i.prototype.value=function(){return this._wrapped}})();
|
||||
@ -0,0 +1,5 @@
|
||||
<li class="dropdown" data-dropdown="dropdown">
|
||||
<a href="{{ pathto(master_doc) }}"
|
||||
class="dropdown-toggle">Chapter</a>
|
||||
<span class="globaltoc">{{ toctree(maxdepth=1) }}</span>
|
||||
</li>
|
||||
@ -0,0 +1,154 @@
|
||||
{% extends "basic/layout.html" %}
|
||||
{% set script_files = script_files + ['_static/bootstrap-dropdown.js', '_static/bootstrap-scrollspy.js'] %}
|
||||
{% set css_files = ['_static/bootstrap.css', '_static/bootstrap-sphinx.css'] + css_files %}
|
||||
|
||||
{# Sidebar: Rework into our Boostrap nav section. #}
|
||||
{% macro navBar() %}
|
||||
<div class="topbar" data-scrollspy="scrollspy" >
|
||||
<div class="topbar-inner">
|
||||
<div class="container">
|
||||
<a class="brand" href="{{ pathto(master_doc) }}">{{ shorttitle|e }}</a>
|
||||
<ul class="nav">
|
||||
{% block sidebartoc %}
|
||||
<li><a href="/">Home</A>
|
||||
{% include "globaltoc.html" %}
|
||||
{% include "localtoc.html" %}
|
||||
{% endblock %}
|
||||
</ul>
|
||||
<ul class="nav secondary-nav">
|
||||
{% block sidebarsearch %}
|
||||
{% include "searchbox.html" %}
|
||||
{% endblock %}
|
||||
</ul>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
{% endmacro %}
|
||||
<p></p>
|
||||
|
||||
{%- block extrahead %}
|
||||
<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>
|
||||
|
||||
<script type="text/javascript">
|
||||
(function() {
|
||||
var po = document.createElement('script'); po.type = 'text/javascript'; po.async = true;
|
||||
po.src = 'https://apis.google.com/js/plusone.js';
|
||||
var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(po, s);
|
||||
})();
|
||||
</script>
|
||||
|
||||
<script>(function(d, s, id) {
|
||||
var js, fjs = d.getElementsByTagName(s)[0];
|
||||
if (d.getElementById(id)) return;
|
||||
js = d.createElement(s); js.id = id;
|
||||
js.src = "//connect.facebook.net/en_US/all.js#xfbml=1";
|
||||
fjs.parentNode.insertBefore(js, fjs);
|
||||
}(document, 'script', 'facebook-jssdk'));</script>
|
||||
{% endblock %}
|
||||
|
||||
{% block header %}{{ navBar() }}{% endblock %}
|
||||
|
||||
{# Silence the sidebar's, relbar's #}
|
||||
{% block sidebar1 %}{% endblock %}
|
||||
{% block sidebar2 %}{% endblock %}
|
||||
{% block relbar1 %}{% endblock %}
|
||||
{% block relbar2 %}{% endblock %}
|
||||
|
||||
{%- block content %}
|
||||
|
||||
<div class="container">
|
||||
{% block body %} {% endblock %}
|
||||
<br/>
|
||||
</div>
|
||||
{%- endblock %}
|
||||
|
||||
{%- block footer %}
|
||||
<footer class="footer">
|
||||
<div class="container">
|
||||
<p>
|
||||
<p>
|
||||
{%- if show_copyright %}
|
||||
{%- if hasdoc('copyright') %}
|
||||
{% trans path=pathto('copyright'), copyright=copyright|e %}© <a href="{{ path }}">Copyright</a> {{ copyright }}.{% endtrans %}<br/>
|
||||
{%- else %}
|
||||
{% trans copyright=copyright|e %}© Copyright {{ copyright }}.{% endtrans %}<br/>
|
||||
{%- endif %}
|
||||
{%- endif %}
|
||||
{%- if last_updated %}
|
||||
{% trans last_updated=last_updated|e %}Last updated on {{ last_updated }}.{% endtrans %}<br/>
|
||||
{%- endif %}
|
||||
</p>
|
||||
</div>
|
||||
</footer>
|
||||
{%- endblock %}
|
||||
|
||||
@ -0,0 +1,5 @@
|
||||
<li class="dropdown" data-dropdown="dropdown">
|
||||
<a href="#"
|
||||
class="dropdown-toggle">{{ _('Page') }}</a>
|
||||
<span class="localtoc">{{ toc }}</span>
|
||||
</li>
|
||||
@ -0,0 +1,8 @@
|
||||
{%- if prev %}
|
||||
<li><a href="{{ prev.link|e }}"
|
||||
title="{{ _('previous chapter') }}">{{ "«"|safe }} {{ prev.title }}</a></li>
|
||||
{%- endif %}
|
||||
{%- if next %}
|
||||
<li><a href="{{ next.link|e }}"
|
||||
title="{{ _('next chapter') }}">{{ next.title }} {{ "»"|safe }}</a></li>
|
||||
{%- endif %}
|
||||
@ -0,0 +1,7 @@
|
||||
{%- if pagename != "search" %}
|
||||
<form class="pull-left" action="{{ pathto('search') }}" 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>
|
||||
{%- endif %}
|
||||
@ -0,0 +1,4 @@
|
||||
{%- if show_source and has_source and sourcename %}
|
||||
<li><a href="{{ pathto('_sources/' + sourcename, true)|e }}"
|
||||
rel="nofollow">{{ _('Source') }}</a></li>
|
||||
{%- endif %}
|
||||
@ -0,0 +1,55 @@
|
||||
/* ============================================================
|
||||
* bootstrap-dropdown.js v1.4.0
|
||||
* http://twitter.github.com/bootstrap/javascript.html#dropdown
|
||||
* ============================================================
|
||||
* Copyright 2011 Twitter, Inc.
|
||||
*
|
||||
* Licensed under the Apache License, Version 2.0 (the "License");
|
||||
* you may not use this file except in compliance with the License.
|
||||
* You may obtain a copy of the License at
|
||||
*
|
||||
* http://www.apache.org/licenses/LICENSE-2.0
|
||||
*
|
||||
* Unless required by applicable law or agreed to in writing, software
|
||||
* distributed under the License is distributed on an "AS IS" BASIS,
|
||||
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||
* See the License for the specific language governing permissions and
|
||||
* limitations under the License.
|
||||
* ============================================================ */
|
||||
|
||||
|
||||
!function( $ ){
|
||||
|
||||
"use strict"
|
||||
|
||||
/* DROPDOWN PLUGIN DEFINITION
|
||||
* ========================== */
|
||||
|
||||
$.fn.dropdown = function ( selector ) {
|
||||
return this.each(function () {
|
||||
$(this).delegate(selector || d, 'click', function (e) {
|
||||
var li = $(this).parent('li')
|
||||
, isActive = li.hasClass('open')
|
||||
|
||||
clearMenus()
|
||||
!isActive && li.toggleClass('open')
|
||||
return false
|
||||
})
|
||||
})
|
||||
}
|
||||
|
||||
/* APPLY TO STANDARD DROPDOWN ELEMENTS
|
||||
* =================================== */
|
||||
|
||||
var d = 'a.menu, .dropdown-toggle'
|
||||
|
||||
function clearMenus() {
|
||||
$(d).parent('li').removeClass('open')
|
||||
}
|
||||
|
||||
$(function () {
|
||||
$('html').bind("click", clearMenus)
|
||||
$('body').dropdown( '[data-dropdown] a.menu, [data-dropdown] .dropdown-toggle' )
|
||||
})
|
||||
|
||||
}( window.jQuery || window.ender );
|
||||
@ -0,0 +1,107 @@
|
||||
/* =============================================================
|
||||
* bootstrap-scrollspy.js v1.4.0
|
||||
* http://twitter.github.com/bootstrap/javascript.html#scrollspy
|
||||
* =============================================================
|
||||
* Copyright 2011 Twitter, Inc.
|
||||
*
|
||||
* Licensed under the Apache License, Version 2.0 (the "License");
|
||||
* you may not use this file except in compliance with the License.
|
||||
* You may obtain a copy of the License at
|
||||
*
|
||||
* http://www.apache.org/licenses/LICENSE-2.0
|
||||
*
|
||||
* Unless required by applicable law or agreed to in writing, software
|
||||
* distributed under the License is distributed on an "AS IS" BASIS,
|
||||
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||
* See the License for the specific language governing permissions and
|
||||
* limitations under the License.
|
||||
* ============================================================== */
|
||||
|
||||
|
||||
!function ( $ ) {
|
||||
|
||||
"use strict"
|
||||
|
||||
var $window = $(window)
|
||||
|
||||
function ScrollSpy( topbar, selector ) {
|
||||
var processScroll = $.proxy(this.processScroll, this)
|
||||
this.$topbar = $(topbar)
|
||||
this.selector = selector || 'li > a'
|
||||
this.refresh()
|
||||
this.$topbar.delegate(this.selector, 'click', processScroll)
|
||||
$window.scroll(processScroll)
|
||||
this.processScroll()
|
||||
}
|
||||
|
||||
ScrollSpy.prototype = {
|
||||
|
||||
refresh: function () {
|
||||
this.targets = this.$topbar.find(this.selector).map(function () {
|
||||
var href = $(this).attr('href')
|
||||
return /^#\w/.test(href) && $(href).length ? href : null
|
||||
})
|
||||
|
||||
this.offsets = $.map(this.targets, function (id) {
|
||||
return $(id).offset().top
|
||||
})
|
||||
}
|
||||
|
||||
, processScroll: function () {
|
||||
var scrollTop = $window.scrollTop() + 10
|
||||
, offsets = this.offsets
|
||||
, targets = this.targets
|
||||
, activeTarget = this.activeTarget
|
||||
, i
|
||||
|
||||
for (i = offsets.length; i--;) {
|
||||
activeTarget != targets[i]
|
||||
&& scrollTop >= offsets[i]
|
||||
&& (!offsets[i + 1] || scrollTop <= offsets[i + 1])
|
||||
&& this.activateButton( targets[i] )
|
||||
}
|
||||
}
|
||||
|
||||
, activateButton: function (target) {
|
||||
this.activeTarget = target
|
||||
|
||||
this.$topbar
|
||||
.find(this.selector).parent('.active')
|
||||
.removeClass('active')
|
||||
|
||||
this.$topbar
|
||||
.find(this.selector + '[href="' + target + '"]')
|
||||
.parent('li')
|
||||
.addClass('active')
|
||||
}
|
||||
|
||||
}
|
||||
|
||||
/* SCROLLSPY PLUGIN DEFINITION
|
||||
* =========================== */
|
||||
|
||||
$.fn.scrollSpy = function( options ) {
|
||||
var scrollspy = this.data('scrollspy')
|
||||
|
||||
if (!scrollspy) {
|
||||
return this.each(function () {
|
||||
$(this).data('scrollspy', new ScrollSpy( this, options ))
|
||||
})
|
||||
}
|
||||
|
||||
if ( options === true ) {
|
||||
return scrollspy
|
||||
}
|
||||
|
||||
if ( typeof options == 'string' ) {
|
||||
scrollspy[options]()
|
||||
}
|
||||
|
||||
return this
|
||||
}
|
||||
|
||||
$(document).ready(function () {
|
||||
$('body').scrollSpy('[data-scrollspy] li > a')
|
||||
})
|
||||
|
||||
}( window.jQuery || window.ender );
|
||||
@ -0,0 +1,24 @@
|
||||
/*
|
||||
* bootstrap-sphinx.css
|
||||
* ~~~~~~~~~~~~~~~~~~~~
|
||||
*
|
||||
* Sphinx stylesheet -- Twitter Bootstrap theme.
|
||||
*/
|
||||
|
||||
body {
|
||||
padding-top: 42px;
|
||||
}
|
||||
|
||||
div.documentwrapper {
|
||||
float: left;
|
||||
width: 100%;
|
||||
}
|
||||
|
||||
{%- block sidebarlogo %}
|
||||
{%- if logo %}
|
||||
.topbar h3 a, .topbar .brand {
|
||||
background: transparent url("{{ logo }}") no-repeat 22px 3px;
|
||||
padding-left: 62px;
|
||||
}
|
||||
{%- endif %}
|
||||
{%- endblock %}
|
||||
File diff suppressed because it is too large
Load Diff
@ -0,0 +1,5 @@
|
||||
# Twitter Bootstrap Theme
|
||||
[theme]
|
||||
inherit = basic
|
||||
stylesheet = basic.css
|
||||
pygments_style = tango
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 31 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 91 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 137 KiB |
@ -0,0 +1,491 @@
|
||||
|
||||
<!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>API & Integrations — Ansible Documentation</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="shortcut icon" href="_static/favicon.ico"/>
|
||||
<link rel="top" title="Ansible Documentation" href="index.html" />
|
||||
<link rel="next" title="Module Development" href="moduledev.html" />
|
||||
<link rel="prev" title="Best Practices" href="bestpractices.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>
|
||||
|
||||
<script type="text/javascript">
|
||||
(function() {
|
||||
var po = document.createElement('script'); po.type = 'text/javascript'; po.async = true;
|
||||
po.src = 'https://apis.google.com/js/plusone.js';
|
||||
var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(po, s);
|
||||
})();
|
||||
</script>
|
||||
|
||||
<script>(function(d, s, id) {
|
||||
var js, fjs = d.getElementsByTagName(s)[0];
|
||||
if (d.getElementById(id)) return;
|
||||
js = d.createElement(s); js.id = id;
|
||||
js.src = "//connect.facebook.net/en_US/all.js#xfbml=1";
|
||||
fjs.parentNode.insertBefore(js, fjs);
|
||||
}(document, 'script', 'facebook-jssdk'));</script>
|
||||
|
||||
</head>
|
||||
<body>
|
||||
<div class="topbar" data-scrollspy="scrollspy" >
|
||||
<div class="topbar-inner">
|
||||
<div class="container">
|
||||
<a class="brand" href="index.html">Ansible Documentation</a>
|
||||
<ul class="nav">
|
||||
|
||||
<li><a href="/">Home</A>
|
||||
<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">Getting Started</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="patterns.html">Inventory & Patterns</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="examples.html">Command Line Examples And Next Steps</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="playbooks2.html">Advanced Playbooks</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="bestpractices.html">Best Practices</a></li>
|
||||
<li class="toctree-l1 current"><a class="current reference internal" href="">API & Integrations</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="moduledev.html">Module Development</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="#">API & Integrations</a><ul>
|
||||
<li><a class="reference internal" href="#python-api">Python API</a><ul>
|
||||
<li><a class="reference internal" href="#detailed-api-example">Detailed API Example</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><a class="reference internal" href="#plugins-repository">Plugins Repository</a></li>
|
||||
<li><a class="reference internal" href="#external-inventory-scripts">External Inventory Scripts</a><ul>
|
||||
<li><a class="reference internal" href="#script-conventions">Script Conventions</a></li>
|
||||
<li><a class="reference internal" href="#example-the-cobbler-external-inventory-script">Example: The Cobbler External Inventory Script</a></li>
|
||||
<li><a class="reference internal" href="#example-aws-ec2-external-inventory-script">Example: AWS EC2 External Inventory Script</a></li>
|
||||
<li><a class="reference internal" href="#example-openstack">Example: OpenStack</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><a class="reference internal" href="#callback-plugins">Callback Plugins</a></li>
|
||||
<li><a class="reference internal" href="#connection-type-plugins">Connection Type Plugins</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="api-integrations">
|
||||
<h1><a class="toc-backref" href="#table-of-contents">API & Integrations</a><a class="headerlink" href="#api-integrations" title="Permalink to this headline">¶</a></h1>
|
||||
<p>There are several interesting ways to use Ansible from an API perspective. You can use
|
||||
the Ansible python API to control nodes, you can extend Ansible to respond to various python events,
|
||||
and you can plug in inventory data from external data sources. Ansible is written in its own
|
||||
API so you have a considerable amount of power across the board.</p>
|
||||
<div class="contents topic" id="table-of-contents">
|
||||
<p class="topic-title first"><cite>Table of contents</cite></p>
|
||||
<ul class="simple">
|
||||
<li><a class="reference internal" href="#api-integrations" id="id2">API & Integrations</a><ul>
|
||||
<li><a class="reference internal" href="#python-api" id="id3">Python API</a></li>
|
||||
<li><a class="reference internal" href="#plugins-repository" id="id4">Plugins Repository</a></li>
|
||||
<li><a class="reference internal" href="#external-inventory-scripts" id="id5">External Inventory Scripts</a></li>
|
||||
<li><a class="reference internal" href="#callback-plugins" id="id6">Callback Plugins</a></li>
|
||||
<li><a class="reference internal" href="#connection-type-plugins" id="id7">Connection Type Plugins</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
</ul>
|
||||
</div>
|
||||
<div class="section" id="python-api">
|
||||
<h2><a class="toc-backref" href="#table-of-contents">Python API</a><a class="headerlink" href="#python-api" title="Permalink to this headline">¶</a></h2>
|
||||
<p>The Python API is very powerful, and is how the ansible CLI and ansible-playbook
|
||||
are implemented.</p>
|
||||
<p>It’s pretty simple:</p>
|
||||
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">ansible.runner</span>
|
||||
|
||||
<span class="n">runner</span> <span class="o">=</span> <span class="n">ansible</span><span class="o">.</span><span class="n">runner</span><span class="o">.</span><span class="n">Runner</span><span class="p">(</span>
|
||||
<span class="n">module_name</span><span class="o">=</span><span class="s">'ping'</span><span class="p">,</span>
|
||||
<span class="n">module_args</span><span class="o">=</span><span class="s">''</span><span class="p">,</span>
|
||||
<span class="n">pattern</span><span class="o">=</span><span class="s">'web*'</span><span class="p">,</span>
|
||||
<span class="n">forks</span><span class="o">=</span><span class="mi">10</span>
|
||||
<span class="p">)</span>
|
||||
<span class="n">datastructure</span> <span class="o">=</span> <span class="n">runner</span><span class="o">.</span><span class="n">run</span><span class="p">()</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>The run method returns results per host, grouped by whether they
|
||||
could be contacted or not. Return types are module specific, as
|
||||
expressed in the ‘ansible-modules’ documentation.:</p>
|
||||
<div class="highlight-python"><pre>{
|
||||
"dark" : {
|
||||
"web1.example.com" : "failure message"
|
||||
}
|
||||
"contacted" : {
|
||||
"web2.example.com" : 1
|
||||
}
|
||||
}</pre>
|
||||
</div>
|
||||
<p>A module can return any type of JSON data it wants, so Ansible can
|
||||
be used as a framework to rapidly build powerful applications and scripts.</p>
|
||||
<div class="section" id="detailed-api-example">
|
||||
<h3>Detailed API Example<a class="headerlink" href="#detailed-api-example" title="Permalink to this headline">¶</a></h3>
|
||||
<p>The following script prints out the uptime information for all hosts:</p>
|
||||
<div class="highlight-python"><div class="highlight"><pre><span class="c">#!/usr/bin/python</span>
|
||||
|
||||
<span class="kn">import</span> <span class="nn">ansible.runner</span>
|
||||
<span class="kn">import</span> <span class="nn">sys</span>
|
||||
|
||||
<span class="c"># construct the ansible runner and execute on all hosts</span>
|
||||
<span class="n">results</span> <span class="o">=</span> <span class="n">ansible</span><span class="o">.</span><span class="n">runner</span><span class="o">.</span><span class="n">Runner</span><span class="p">(</span>
|
||||
<span class="n">pattern</span><span class="o">=</span><span class="s">'*'</span><span class="p">,</span> <span class="n">forks</span><span class="o">=</span><span class="mi">10</span><span class="p">,</span>
|
||||
<span class="n">module_name</span><span class="o">=</span><span class="s">'command'</span><span class="p">,</span> <span class="n">module_args</span><span class="o">=</span><span class="s">'/usr/bin/uptime'</span><span class="p">,</span>
|
||||
<span class="p">)</span><span class="o">.</span><span class="n">run</span><span class="p">()</span>
|
||||
|
||||
<span class="k">if</span> <span class="n">results</span> <span class="ow">is</span> <span class="bp">None</span><span class="p">:</span>
|
||||
<span class="k">print</span> <span class="s">"No hosts found"</span>
|
||||
<span class="n">sys</span><span class="o">.</span><span class="n">exit</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span>
|
||||
|
||||
<span class="k">print</span> <span class="s">"UP ***********"</span>
|
||||
<span class="k">for</span> <span class="p">(</span><span class="n">hostname</span><span class="p">,</span> <span class="n">result</span><span class="p">)</span> <span class="ow">in</span> <span class="n">results</span><span class="p">[</span><span class="s">'contacted'</span><span class="p">]</span><span class="o">.</span><span class="n">items</span><span class="p">():</span>
|
||||
<span class="k">if</span> <span class="ow">not</span> <span class="s">'failed'</span> <span class="ow">in</span> <span class="n">result</span><span class="p">:</span>
|
||||
<span class="k">print</span> <span class="s">"</span><span class="si">%s</span><span class="s"> >>> </span><span class="si">%s</span><span class="s">"</span> <span class="o">%</span> <span class="p">(</span><span class="n">hostname</span><span class="p">,</span> <span class="n">result</span><span class="p">[</span><span class="s">'stdout'</span><span class="p">])</span>
|
||||
|
||||
<span class="k">print</span> <span class="s">"FAILED *******"</span>
|
||||
<span class="k">for</span> <span class="p">(</span><span class="n">hostname</span><span class="p">,</span> <span class="n">result</span><span class="p">)</span> <span class="ow">in</span> <span class="n">results</span><span class="p">[</span><span class="s">'contacted'</span><span class="p">]</span><span class="o">.</span><span class="n">items</span><span class="p">():</span>
|
||||
<span class="k">if</span> <span class="s">'failed'</span> <span class="ow">in</span> <span class="n">result</span><span class="p">:</span>
|
||||
<span class="k">print</span> <span class="s">"</span><span class="si">%s</span><span class="s"> >>> </span><span class="si">%s</span><span class="s">"</span> <span class="o">%</span> <span class="p">(</span><span class="n">hostname</span><span class="p">,</span> <span class="n">result</span><span class="p">[</span><span class="s">'msg'</span><span class="p">])</span>
|
||||
|
||||
<span class="k">print</span> <span class="s">"DOWN *********"</span>
|
||||
<span class="k">for</span> <span class="p">(</span><span class="n">hostname</span><span class="p">,</span> <span class="n">result</span><span class="p">)</span> <span class="ow">in</span> <span class="n">results</span><span class="p">[</span><span class="s">'dark'</span><span class="p">]</span><span class="o">.</span><span class="n">items</span><span class="p">():</span>
|
||||
<span class="k">print</span> <span class="s">"</span><span class="si">%s</span><span class="s"> >>> </span><span class="si">%s</span><span class="s">"</span> <span class="o">%</span> <span class="p">(</span><span class="n">hostname</span><span class="p">,</span> <span class="n">result</span><span class="p">)</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>Advanced programmers may also wish to read the source to ansible itself, for
|
||||
it uses the Runner() API (with all available options) to implement the
|
||||
command line tools <tt class="docutils literal"><span class="pre">ansible</span></tt> and <tt class="docutils literal"><span class="pre">ansible-playbook</span></tt>.</p>
|
||||
</div>
|
||||
</div>
|
||||
<div class="section" id="plugins-repository">
|
||||
<h2><a class="toc-backref" href="#table-of-contents">Plugins Repository</a><a class="headerlink" href="#plugins-repository" title="Permalink to this headline">¶</a></h2>
|
||||
<p>The remainder of features in the API docs have components available in the <a class="reference external" href="http://github.com/ansible/ansible-plugins">ansible-plugins</a> repository. Please consult this repository for more information. Send us a github pull request if you develop any interesting features.</p>
|
||||
</div>
|
||||
<div class="section" id="external-inventory-scripts">
|
||||
<h2><a class="toc-backref" href="#table-of-contents">External Inventory Scripts</a><a class="headerlink" href="#external-inventory-scripts" title="Permalink to this headline">¶</a></h2>
|
||||
<p>Often a user of a configuration management system will want to keep inventory
|
||||
in a different system. Frequent examples include LDAP, <a class="reference external" href="http://cobbler.github.com">Cobbler</a>,
|
||||
or a piece of expensive enterprisey CMDB software. Ansible easily supports all
|
||||
of these options via an external inventory system. The ansible-plugins repo contains some of these already – including options for EC2/Eucalyptus and OpenStack, which will be detailed below.</p>
|
||||
<p>It’s possible to write an external inventory script in any language. 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>
|
||||
<div class="section" id="script-conventions">
|
||||
<h3>Script Conventions<a class="headerlink" href="#script-conventions" title="Permalink to this headline">¶</a></h3>
|
||||
<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>
|
||||
<div class="highlight-python"><div class="highlight"><pre><span class="p">{</span>
|
||||
<span class="s">'databases'</span> <span class="p">:</span> <span class="p">[</span> <span class="s">'host1.example.com'</span><span class="p">,</span> <span class="s">'host2.example.com'</span> <span class="p">],</span>
|
||||
<span class="s">'webservers'</span> <span class="p">:</span> <span class="p">[</span> <span class="s">'host2.example.com'</span><span class="p">,</span> <span class="s">'host3.example.com'</span> <span class="p">],</span>
|
||||
<span class="s">'atlanta'</span> <span class="p">:</span> <span class="p">[</span> <span class="s">'host1.example.com'</span><span class="p">,</span> <span class="s">'host4.example.com'</span><span class="p">,</span> <span class="s">'host5.example.com'</span> <span class="p">]</span>
|
||||
<span class="p">}</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<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 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>
|
||||
<div class="highlight-python"><div class="highlight"><pre><span class="p">{</span>
|
||||
<span class="s">'favcolor'</span> <span class="p">:</span> <span class="s">'red'</span><span class="p">,</span>
|
||||
<span class="s">'ntpserver'</span> <span class="p">:</span> <span class="s">'wolf.example.com'</span><span class="p">,</span>
|
||||
<span class="s">'monitoring'</span> <span class="p">:</span> <span class="s">'pack.example.com'</span>
|
||||
<span class="p">}</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
</div>
|
||||
<div class="section" id="example-the-cobbler-external-inventory-script">
|
||||
<h3>Example: The Cobbler External Inventory Script<a class="headerlink" href="#example-the-cobbler-external-inventory-script" title="Permalink to this headline">¶</a></h3>
|
||||
<p>It is expected that many Ansible users will also be <a class="reference external" href="http://cobbler.github.com">Cobbler</a> users. Cobbler has a generic
|
||||
layer that allows it to represent data for multiple configuration management systems (even at the same time), and has
|
||||
been referred to as a ‘lightweight CMDB’ by some admins. This particular script will communicate with Cobbler
|
||||
using Cobbler’s XMLRPC API.</p>
|
||||
<p>To tie Ansible’s inventory to Cobbler (optional), copy <a class="reference external" href="https://github.com/ansible/ansible-plugins/blob/master/inventory/cobbler.py">this script</a> to /etc/ansible/hosts and <cite>chmod +x</cite> the file. cobblerd will now need
|
||||
to be running when you are using Ansible.</p>
|
||||
<p>Test the file by running <cite>./etc/ansible/hosts</cite> directly. You should see some JSON data output, but it may not have
|
||||
anything in it just yet.</p>
|
||||
<p>Let’s explore what this does. In cobbler, assume a scenario somewhat like the following:</p>
|
||||
<div class="highlight-python"><pre>cobbler profile add --name=webserver --distro=CentOS6-x86_64
|
||||
cobbler profile edit --name=webserver --mgmt-classes="webserver" --ksmeta="a=2 b=3"
|
||||
cobbler system edit --name=foo --dns-name="foo.example.com" --mgmt-classes="atlanta" --ksmeta="c=4"
|
||||
cobbler system edit --name=bar --dns-name="bar.example.com" --mgmt-classes="atlanta" --ksmeta="c=5"</pre>
|
||||
</div>
|
||||
<p>In the example above, the system ‘foo.example.com’ will be addressable by ansible directly, but will also be addressable when using the group names ‘webserver’ or ‘atlanta’. Since Ansible uses SSH, we’ll try to contract system foo over ‘foo.example.com’, only, never just ‘foo’. Similarly, if you try “ansible foo” it wouldn’t find the system... but “ansible ‘foo*’” would, because the system DNS name starts with ‘foo’.</p>
|
||||
<p>The script doesn’t just provide host and group info. In addition, as a bonus, when the ‘setup’ module is run (which happens automatically when using playbooks), the variables ‘a’, ‘b’, and ‘c’ will all be auto-populated in the templates:</p>
|
||||
<div class="highlight-python"><pre># file: /srv/motd.j2
|
||||
Welcome, I am templated with a value of a={{ a }}, b={{ b }}, and c={{ c }}</pre>
|
||||
</div>
|
||||
<p>Which could be executed just like this:</p>
|
||||
<div class="highlight-python"><pre>ansible webserver -m setup
|
||||
ansible webserver -m template -a "src=/tmp/motd.j2 dest=/etc/motd"</pre>
|
||||
</div>
|
||||
<div class="admonition note">
|
||||
<p class="first admonition-title">Note</p>
|
||||
<p class="last">The name ‘webserver’ came from cobbler, as did the variables for
|
||||
the config file. You can still pass in your own variables like
|
||||
normal in Ansible, but variables from the external inventory script
|
||||
will override any that have the same name.</p>
|
||||
</div>
|
||||
<p>So, with the template above (motd.j2), this would result in the following data being written to /etc/motd for system ‘foo’:</p>
|
||||
<div class="highlight-python"><pre>Welcome, I am templated with a value of a=2, b=3, and c=4</pre>
|
||||
</div>
|
||||
<p>And on system ‘bar’ (bar.example.com):</p>
|
||||
<div class="highlight-python"><pre>Welcome, I am templated with a value of a=2, b=3, and c=5</pre>
|
||||
</div>
|
||||
<p>And technically, though there is no major good reason to do it, this also works too:</p>
|
||||
<div class="highlight-python"><pre>ansible webserver -m shell -a "echo {{ a }}"</pre>
|
||||
</div>
|
||||
<p>So in other words, you can use those variables in arguments/actions as well. You might use this to name
|
||||
a conf.d file appropriately or something similar. Who knows?</p>
|
||||
<p>So that’s the Cobbler integration support – using the cobbler script as an example, it should be trivial to adapt Ansible to pull inventory, as well as variable information, from any data source. If you create anything interesting, please share with the mailing list, and we can keep it in the source code tree for others to use.</p>
|
||||
</div>
|
||||
<div class="section" id="example-aws-ec2-external-inventory-script">
|
||||
<h3>Example: AWS EC2 External Inventory Script<a class="headerlink" href="#example-aws-ec2-external-inventory-script" title="Permalink to this headline">¶</a></h3>
|
||||
<p>If you use Amazon Web Services EC2, maintaining an inventory file might not be the best approach. For this reason, you can use the <a class="reference external" href="https://github.com/ansible/ansible-plugins/blob/master/inventory/ec2.py">EC2 external inventory</a> script.</p>
|
||||
<p>You can use this script in one of two ways. The easiest is to use Ansible’s <tt class="docutils literal"><span class="pre">-i</span></tt> command line option and specify the path to the script.</p>
|
||||
<blockquote>
|
||||
<div>ansible -i ec2.py -u ubuntu us-east-1d -m ping</div></blockquote>
|
||||
<p>The second option is to copy the script to <cite>/etc/ansible/hosts</cite> and <cite>chmod +x</cite> it. You will also need to copy the <tt class="docutils literal"><span class="pre">ec2.ini</span></tt> file to <cite>/etc/ansible/ec2.ini</cite>. Then you can run ansible as you would normally.</p>
|
||||
<p>To successfully make an API call to AWS, you will need to configure Boto (the Python interface to AWS). There are a <a class="reference external" href="http://docs.pythonboto.org/en/latest/boto_config_tut.html">variety of methods</a> available, but the simplest is just to export two environment variables:</p>
|
||||
<blockquote>
|
||||
<div>export AWS_ACCESS_KEY_ID=’AK123’
|
||||
export AWS_SECRET_ACCESS_KEY=’abc123’</div></blockquote>
|
||||
<p>You can test the script by itself to make sure your config is correct</p>
|
||||
<blockquote>
|
||||
<div>cd examples/scripts
|
||||
./ec2_external_inventory.py –list</div></blockquote>
|
||||
<p>After a few moments, you should see your entire EC2 inventory across all regions in JSON.</p>
|
||||
<p>Since each region requires its own API call, if you are only using a small set of regions, feel free to edit <tt class="docutils literal"><span class="pre">ec2.ini</span></tt> and list only the regions you are interested in. There are other config options in <tt class="docutils literal"><span class="pre">ec2.ini</span></tt> including cache control, and destination variables.</p>
|
||||
<p>At their heart, inventory files are simply a mapping from some name to a destination address. The default <tt class="docutils literal"><span class="pre">ec2.ini</span></tt> settings are configured for running Ansible from outside EC2 (from your laptop for example). If you are running Ansible from within EC2, internal DNS names and IP addresses may make more sense than public DNS names. In this case, you can modify the <tt class="docutils literal"><span class="pre">destination_variable</span></tt> in <tt class="docutils literal"><span class="pre">ec2.ini</span></tt> to be the private DNS name of an instance. This is particularly important when running Ansible within a private subnet inside a VPC, where the only way to access an instance is via its private IP address. For VPC instances, <cite>vpc_destination_variable</cite> in <tt class="docutils literal"><span class="pre">ec2.ini</span></tt> provides a means of using which ever <a class="reference external" href="http://docs.pythonboto.org/en/latest/ref/ec2.html#module-boto.ec2.instance">boto.ec2.instance variable</a> makes the most sense for your use case.</p>
|
||||
<p>The EC2 external inventory provides mappings to instances from several groups:</p>
|
||||
<dl class="docutils">
|
||||
<dt>Instance ID</dt>
|
||||
<dd>These are groups of one since instance IDs are unique.
|
||||
e.g.
|
||||
<tt class="docutils literal"><span class="pre">i-00112233</span></tt>
|
||||
<tt class="docutils literal"><span class="pre">i-a1b1c1d1</span></tt></dd>
|
||||
<dt>Region</dt>
|
||||
<dd>A group of all instances in an AWS region.
|
||||
e.g.
|
||||
<tt class="docutils literal"><span class="pre">us-east-1</span></tt>
|
||||
<tt class="docutils literal"><span class="pre">us-west-2</span></tt></dd>
|
||||
<dt>Availability Zone</dt>
|
||||
<dd>A group of all instances in an availability zone.
|
||||
e.g.
|
||||
<tt class="docutils literal"><span class="pre">us-east-1a</span></tt>
|
||||
<tt class="docutils literal"><span class="pre">us-east-1b</span></tt></dd>
|
||||
<dt>Security Group</dt>
|
||||
<dd>Instances belong to one or more security groups. A group is created for each security group, with all characters except alphanumerics, dashes (-) converted to underscores (_). Each group is prefixed by <tt class="docutils literal"><span class="pre">security_group_</span></tt>
|
||||
e.g.
|
||||
<tt class="docutils literal"><span class="pre">security_group_default</span></tt>
|
||||
<tt class="docutils literal"><span class="pre">security_group_webservers</span></tt>
|
||||
<tt class="docutils literal"><span class="pre">security_group_Pete_s_Fancy_Group</span></tt></dd>
|
||||
<dt>Tags</dt>
|
||||
<dd>Each instance can have a variety of key/value pairs associated with it called Tags. The most common tag key is ‘Name’, though anything is possible. Each key/value pair is its own group of instances, again with special characters converted to underscores, in the format <tt class="docutils literal"><span class="pre">tag_KEY_VALUE</span></tt>
|
||||
e.g.
|
||||
<tt class="docutils literal"><span class="pre">tag_Name_Web</span></tt>
|
||||
<tt class="docutils literal"><span class="pre">tag_Name_redis-master-001</span></tt>
|
||||
<tt class="docutils literal"><span class="pre">tag_aws_cloudformation_logical-id_WebServerGroup</span></tt></dd>
|
||||
</dl>
|
||||
<p>When the Ansible is interacting with a specific server, the EC2 inventory script is called again with the <tt class="docutils literal"><span class="pre">--host</span> <span class="pre">HOST</span></tt> option. This looks up the HOST in the index cache to get the instance ID, and then makes an API call to AWS to get information about that specific instance. It then makes information about that instance available as variables to your playbooks. Each variable is prefixed by <tt class="docutils literal"><span class="pre">ec2_</span></tt>. Here are some of the variables available:</p>
|
||||
<ul class="simple">
|
||||
<li>ec2_architecture</li>
|
||||
<li>ec2_description</li>
|
||||
<li>ec2_dns_name</li>
|
||||
<li>ec2_id</li>
|
||||
<li>ec2_image_id</li>
|
||||
<li>ec2_instance_type</li>
|
||||
<li>ec2_ip_address</li>
|
||||
<li>ec2_kernel</li>
|
||||
<li>ec2_key_name</li>
|
||||
<li>ec2_launch_time</li>
|
||||
<li>ec2_monitored</li>
|
||||
<li>ec2_ownerId</li>
|
||||
<li>ec2_placement</li>
|
||||
<li>ec2_platform</li>
|
||||
<li>ec2_previous_state</li>
|
||||
<li>ec2_private_dns_name</li>
|
||||
<li>ec2_private_ip_address</li>
|
||||
<li>ec2_public_dns_name</li>
|
||||
<li>ec2_ramdisk</li>
|
||||
<li>ec2_region</li>
|
||||
<li>ec2_root_device_name</li>
|
||||
<li>ec2_root_device_type</li>
|
||||
<li>ec2_security_group_ids</li>
|
||||
<li>ec2_security_group_names</li>
|
||||
<li>ec2_spot_instance_request_id</li>
|
||||
<li>ec2_state</li>
|
||||
<li>ec2_state_code</li>
|
||||
<li>ec2_state_reason</li>
|
||||
<li>ec2_status</li>
|
||||
<li>ec2_subnet_id</li>
|
||||
<li>ec2_tag_Name</li>
|
||||
<li>ec2_tenancy</li>
|
||||
<li>ec2_virtualization_type</li>
|
||||
<li>ec2_vpc_id</li>
|
||||
</ul>
|
||||
<p>Both <tt class="docutils literal"><span class="pre">ec2_security_group_ids</span></tt> and <tt class="docutils literal"><span class="pre">ec2_security_group_names</span></tt> are comma-separated lists of all security groups. Each EC2 tag is a variable in the format <tt class="docutils literal"><span class="pre">ec2_tag_KEY</span></tt>.</p>
|
||||
<p>To see the complete list of variables available for an instance, run the script by itself:</p>
|
||||
<div class="highlight-python"><pre>cd examples/scripts
|
||||
./ec2_external_inventory.py --host ec2-12-12-12-12.compute-1.amazonaws.com</pre>
|
||||
</div>
|
||||
</div>
|
||||
<div class="section" id="example-openstack">
|
||||
<h3>Example: OpenStack<a class="headerlink" href="#example-openstack" title="Permalink to this headline">¶</a></h3>
|
||||
<p>Though not detailed here in as much depth as the EC2 module, there’s also a OpenStack Nova external inventory source in the ansible-plugins repository. See the inline comments in the module source.</p>
|
||||
</div>
|
||||
</div>
|
||||
<div class="section" id="callback-plugins">
|
||||
<h2><a class="toc-backref" href="#table-of-contents">Callback Plugins</a><a class="headerlink" href="#callback-plugins" title="Permalink to this headline">¶</a></h2>
|
||||
<p>Ansible can be configured via code to respond to external events. This can include enhancing logging, signalling an external software
|
||||
system, or even (yes, really) making sound effects. Some examples are contained in the ansible-plugins repository.</p>
|
||||
</div>
|
||||
<div class="section" id="connection-type-plugins">
|
||||
<h2><a class="toc-backref" href="#table-of-contents">Connection Type Plugins</a><a class="headerlink" href="#connection-type-plugins" title="Permalink to this headline">¶</a></h2>
|
||||
<p>By default, ansible ships with a ‘paramiko’ SSH, native ssh (just called ‘ssh’), and ‘local’ connection type, which can be used
|
||||
in playbooks and with /usr/bin/ansible to decide how you want to talk to remote machines. The basics of these connection types
|
||||
are covered in the ‘getting started’ section. Should you want to extend Ansible to support other transports (SNMP? Message bus?
|
||||
Carrier Pigeon?) it’s as simple as copying the format of one of the existing modules and dropping it into the connection plugins
|
||||
directory.</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>List of built-in modules</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>
|
||||
|
||||
|
||||
<br/>
|
||||
</div>
|
||||
<footer class="footer">
|
||||
<div class="container">
|
||||
<p>
|
||||
<p>
|
||||
© Copyright 2012 Michael DeHaan.<br/>
|
||||
Last updated on Oct 08, 2012.<br/>
|
||||
</p>
|
||||
</div>
|
||||
</footer>
|
||||
</body>
|
||||
</html>
|
||||
@ -0,0 +1,335 @@
|
||||
|
||||
<!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>Best Practices — Ansible Documentation</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="shortcut icon" href="_static/favicon.ico"/>
|
||||
<link rel="top" title="Ansible Documentation" href="index.html" />
|
||||
<link rel="next" title="API & Integrations" href="api.html" />
|
||||
<link rel="prev" title="Advanced Playbooks" href="playbooks2.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>
|
||||
|
||||
<script type="text/javascript">
|
||||
(function() {
|
||||
var po = document.createElement('script'); po.type = 'text/javascript'; po.async = true;
|
||||
po.src = 'https://apis.google.com/js/plusone.js';
|
||||
var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(po, s);
|
||||
})();
|
||||
</script>
|
||||
|
||||
<script>(function(d, s, id) {
|
||||
var js, fjs = d.getElementsByTagName(s)[0];
|
||||
if (d.getElementById(id)) return;
|
||||
js = d.createElement(s); js.id = id;
|
||||
js.src = "//connect.facebook.net/en_US/all.js#xfbml=1";
|
||||
fjs.parentNode.insertBefore(js, fjs);
|
||||
}(document, 'script', 'facebook-jssdk'));</script>
|
||||
|
||||
</head>
|
||||
<body>
|
||||
<div class="topbar" data-scrollspy="scrollspy" >
|
||||
<div class="topbar-inner">
|
||||
<div class="container">
|
||||
<a class="brand" href="index.html">Ansible Documentation</a>
|
||||
<ul class="nav">
|
||||
|
||||
<li><a href="/">Home</A>
|
||||
<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">Getting Started</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="patterns.html">Inventory & Patterns</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="examples.html">Command Line Examples And Next Steps</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="playbooks2.html">Advanced Playbooks</a></li>
|
||||
<li class="toctree-l1 current"><a class="current reference internal" href="">Best Practices</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="api.html">API & Integrations</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="moduledev.html">Module Development</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="#">Best Practices</a><ul>
|
||||
<li><a class="reference internal" href="#always-mention-state">Always Mention State</a></li>
|
||||
<li><a class="reference internal" href="#group-by-roles">Group By Roles</a></li>
|
||||
<li><a class="reference internal" href="#directory-organization">Directory Organization</a></li>
|
||||
<li><a class="reference internal" href="#bundling-ansible-modules-with-playbooks">Bundling Ansible Modules With Playbooks</a></li>
|
||||
<li><a class="reference internal" href="#miscellaneous-tips">Miscellaneous Tips</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="best-practices">
|
||||
<h1><a class="toc-backref" href="#contents">Best Practices</a><a class="headerlink" href="#best-practices" title="Permalink to this headline">¶</a></h1>
|
||||
<p>Here are some tips for making the most of Ansible.</p>
|
||||
<div class="contents topic" id="contents">
|
||||
<p class="topic-title first">Contents</p>
|
||||
<ul class="simple">
|
||||
<li><a class="reference internal" href="#best-practices" id="id1">Best Practices</a><ul>
|
||||
<li><a class="reference internal" href="#always-mention-state" id="id2">Always Mention State</a></li>
|
||||
<li><a class="reference internal" href="#group-by-roles" id="id3">Group By Roles</a></li>
|
||||
<li><a class="reference internal" href="#directory-organization" id="id4">Directory Organization</a></li>
|
||||
<li><a class="reference internal" href="#bundling-ansible-modules-with-playbooks" id="id5">Bundling Ansible Modules With Playbooks</a></li>
|
||||
<li><a class="reference internal" href="#miscellaneous-tips" id="id6">Miscellaneous Tips</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
</ul>
|
||||
</div>
|
||||
<div class="section" id="always-mention-state">
|
||||
<h2><a class="toc-backref" href="#contents">Always Mention State</a><a class="headerlink" href="#always-mention-state" title="Permalink to this headline">¶</a></h2>
|
||||
<p>The ‘state’ parameter is optional to a lot of modules. Whether
|
||||
‘state=present’ or ‘state=absent’, it’s always best to leave that
|
||||
parameter in your playbooks to make it clear, especially as some
|
||||
modules support additional states.</p>
|
||||
</div>
|
||||
<div class="section" id="group-by-roles">
|
||||
<h2><a class="toc-backref" href="#contents">Group By Roles</a><a class="headerlink" href="#group-by-roles" title="Permalink to this headline">¶</a></h2>
|
||||
<p>A system can be in multiple groups. See <a class="reference internal" href="patterns.html"><em>Inventory & Patterns</em></a>. Having groups named after things like
|
||||
<em>webservers</em> and <em>dbservers</em> is repeated in the examples because it’s a very powerful concept.</p>
|
||||
<p>This allows playbooks to target machines based on role, as well as to assign role specific variables
|
||||
using the group variable system.</p>
|
||||
</div>
|
||||
<div class="section" id="directory-organization">
|
||||
<h2><a class="toc-backref" href="#contents">Directory Organization</a><a class="headerlink" href="#directory-organization" title="Permalink to this headline">¶</a></h2>
|
||||
<p>Playbooks should be organized like this:</p>
|
||||
<div class="highlight-python"><pre># root of source control repository
|
||||
├── acme/
|
||||
│ ├── setup.yml
|
||||
│ └── stop.yml
|
||||
├── files/
|
||||
│ └── some_file_path_foo.conf
|
||||
├── handlers/
|
||||
│ └── main.yml
|
||||
├── tasks/
|
||||
│ ├── setup.yml
|
||||
│ └── stop.yml
|
||||
├── templates/
|
||||
│ ├── etc_acme_conf_acme.conf
|
||||
│ └── etc_other_conf_other.conf
|
||||
├── vars/
|
||||
│ └── main.yml
|
||||
└── global_vars.yml</pre>
|
||||
</div>
|
||||
<p>Any directories or files not needed can be omitted. Not all modules
|
||||
may require ‘vars’ or ‘files’ sections, though most will require
|
||||
‘handlers’, ‘tasks’, and ‘templates’. To review what each of
|
||||
these sections do, see <a class="reference internal" href="playbooks.html"><em>Playbooks</em></a> and <a class="reference internal" href="playbooks2.html"><em>Advanced Playbooks</em></a>.</p>
|
||||
<p>The acme/setup.yml playbook would be as simple as:</p>
|
||||
<div class="highlight-python"><pre>---
|
||||
- hosts: webservers
|
||||
user: root
|
||||
|
||||
vars_files:
|
||||
- ../global_vars.yml
|
||||
- vars/main.yml
|
||||
tasks:
|
||||
- include: tasks/setup.yml
|
||||
handlers:
|
||||
- include: handlers/main.yml</pre>
|
||||
</div>
|
||||
<p>The tasks are individually broken out in ‘acme/tasks/setup.yml’, and handlers, which are common to all task files,
|
||||
are contained in ‘acme/handlers/main.yml’. As a reminder, handlers are mostly just used to notify services to restart
|
||||
when things change, and these are described in <a class="reference internal" href="playbooks.html"><em>Playbooks</em></a>.</p>
|
||||
<p>Including more than one setup file or more than one handlers file is of course legal.</p>
|
||||
</div>
|
||||
<div class="section" id="bundling-ansible-modules-with-playbooks">
|
||||
<h2><a class="toc-backref" href="#contents">Bundling Ansible Modules With Playbooks</a><a class="headerlink" href="#bundling-ansible-modules-with-playbooks" title="Permalink to this headline">¶</a></h2>
|
||||
<p class="versionadded">
|
||||
<span class="versionmodified">New in version 0.5.</span></p>
|
||||
<p>If a playbook has a ”./library” directory relative to it’s YAML file,
|
||||
this directory can be used to add ansible modules that will
|
||||
automatically be in the ansible module path. This is a great way to
|
||||
keep modules that go with a playbook together.</p>
|
||||
</div>
|
||||
<div class="section" id="miscellaneous-tips">
|
||||
<h2><a class="toc-backref" href="#contents">Miscellaneous Tips</a><a class="headerlink" href="#miscellaneous-tips" title="Permalink to this headline">¶</a></h2>
|
||||
<p>When you can do something simply, do something simply. Do not reach
|
||||
to use every feature of Ansible together, all at once. Use what works
|
||||
for you. For example, you should probably not need ‘vars’,
|
||||
‘vars_files’, ‘vars_prompt’ and ‘–extra-vars’ all at once,
|
||||
while also using an external inventory file.</p>
|
||||
<p>Optimize for readability. Whitespace between sections of YAML
|
||||
documents and in between tasks is strongly encouraged, as is usage of
|
||||
YAML comments, which start with ‘#’. It is also useful to comment
|
||||
at the top of each file the purpose of the individual file and the
|
||||
author, including email address.</p>
|
||||
<p>It is possible to leave off the ‘name’ for a given task, though it
|
||||
is recommended to provide a descriptive comment about why something is
|
||||
being done instead.</p>
|
||||
<p>Use version control. Keep your playbooks and inventory file in git
|
||||
(or another version control system), and commit when you make changes
|
||||
to them. This way you have an audit trail describing when and why you
|
||||
changed the rules automating your infrastructure.</p>
|
||||
<p>Resist the urge to write the same playbooks and configuration files
|
||||
for heterogeneous distributions. While lots of software packages
|
||||
claim to make this easy on you, the configuration files are often
|
||||
quite different, to the point where it would be easier to treat them
|
||||
as different playbooks. This is why, for example, Ansible has a
|
||||
separate ‘yum’ and ‘apt’ module. Yum and apt have different
|
||||
capabilities, and we don’t want to code for the least common
|
||||
denominator.</p>
|
||||
<p>Use variables for user tunable settings versus having constants in the
|
||||
tasks file or templates, so that it is easy to reconfigure a playbook.
|
||||
Think about this as exposing the knobs to things you would like to
|
||||
tweak.</p>
|
||||
<p>Since a system can be in more than one group, if you have multiple
|
||||
datacenters or sites, consider putting systems into groups by role,
|
||||
but also different groups by geography. This allows you to assign
|
||||
different variables to different geographies.</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="YAMLSyntax.html"><em>YAML Syntax</em></a></dt>
|
||||
<dd>Learn about YAML syntax</dd>
|
||||
<dt><a class="reference internal" href="playbooks.html"><em>Playbooks</em></a></dt>
|
||||
<dd>Review the basic playbook features</dd>
|
||||
<dt><a class="reference internal" href="modules.html"><em>Ansible Modules</em></a></dt>
|
||||
<dd>Learn about available modules</dd>
|
||||
<dt><a class="reference internal" href="moduledev.html"><em>Module Development</em></a></dt>
|
||||
<dd>Learn how to extend Ansible by writing your own modules</dd>
|
||||
<dt><a class="reference internal" href="patterns.html"><em>Inventory & Patterns</em></a></dt>
|
||||
<dd>Learn about how to select hosts</dd>
|
||||
<dt><a class="reference external" href="https://github.com/ansible/ansible/tree/devel/examples/playbooks">Github examples directory</a></dt>
|
||||
<dd>Complete playbook files from the github project source</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>
|
||||
</dl>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
|
||||
<br/>
|
||||
</div>
|
||||
<footer class="footer">
|
||||
<div class="container">
|
||||
<p>
|
||||
<p>
|
||||
© Copyright 2012 Michael DeHaan.<br/>
|
||||
Last updated on Oct 08, 2012.<br/>
|
||||
</p>
|
||||
</div>
|
||||
</footer>
|
||||
</body>
|
||||
</html>
|
||||
@ -0,0 +1,97 @@
|
||||
#!/usr/bin/env python
|
||||
# (c) 2012, Michael DeHaan <michael.dehaan@gmail.com>
|
||||
#
|
||||
# This file is part of the Ansible Documentation
|
||||
#
|
||||
# Ansible is free software: you can redistribute it and/or modify
|
||||
# it under the terms of the GNU General Public License as published by
|
||||
# the Free Software Foundation, either version 3 of the License, or
|
||||
# (at your option) any later version.
|
||||
#
|
||||
# Ansible is distributed in the hope that it will be useful,
|
||||
# but WITHOUT ANY WARRANTY; without even the implied warranty of
|
||||
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
||||
# GNU General Public License for more details.
|
||||
#
|
||||
# You should have received a copy of the GNU General Public License
|
||||
# along with Ansible. If not, see <http://www.gnu.org/licenses/>.
|
||||
|
||||
__docformat__ = 'restructuredtext'
|
||||
|
||||
import os
|
||||
import sys
|
||||
import traceback
|
||||
from sphinx.application import Sphinx
|
||||
import os
|
||||
|
||||
|
||||
class SphinxBuilder(object):
|
||||
"""
|
||||
Creates HTML documentation using Sphinx.
|
||||
"""
|
||||
|
||||
def __init__(self):
|
||||
"""
|
||||
Run the DocCommand.
|
||||
"""
|
||||
print "Creating html documentation ..."
|
||||
|
||||
try:
|
||||
buildername = 'html'
|
||||
|
||||
outdir = os.path.abspath(os.getcwd())
|
||||
# Create the output directory if it doesn't exist
|
||||
if not os.access(outdir, os.F_OK):
|
||||
os.mkdir(outdir)
|
||||
|
||||
doctreedir = os.path.join('./', '.doctrees')
|
||||
|
||||
confdir = os.path.abspath('./')
|
||||
srcdir = os.path.abspath('rst')
|
||||
freshenv = True
|
||||
|
||||
# Create the builder
|
||||
app = Sphinx(srcdir,
|
||||
confdir,
|
||||
outdir,
|
||||
doctreedir,
|
||||
buildername,
|
||||
{},
|
||||
sys.stdout,
|
||||
sys.stderr,
|
||||
freshenv)
|
||||
|
||||
app.builder.build_all()
|
||||
|
||||
except ImportError, ie:
|
||||
traceback.print_exc()
|
||||
except Exception, ex:
|
||||
print >> sys.stderr, "FAIL! exiting ... (%s)" % ex
|
||||
|
||||
def build_docs(self):
|
||||
self.app.builder.build_all()
|
||||
|
||||
|
||||
def build_rst_docs():
|
||||
docgen = SphinxBuilder()
|
||||
|
||||
if __name__ == '__main__':
|
||||
if '-h' in sys.argv or '--help' in sys.argv:
|
||||
print "This script builds the html documentation from rst/asciidoc sources.\n"
|
||||
print " Run 'make docs' to build everything."
|
||||
print " Run 'make viewdocs' to build and then preview in a web browser."
|
||||
sys.exit(0)
|
||||
|
||||
# The 'htmldocs' make target will call this scrip twith the 'rst'
|
||||
# parameter' We don't need to run the 'htmlman' target then.
|
||||
if "rst" in sys.argv:
|
||||
build_rst_docs()
|
||||
else:
|
||||
# By default, preform the rst->html transformation and then
|
||||
# the asciidoc->html trasnformation
|
||||
build_rst_docs()
|
||||
|
||||
if "view" in sys.argv:
|
||||
import webbrowser
|
||||
if not webbrowser.open('index.html'):
|
||||
print >> sys.stderr, "Could not open on your webbrowser."
|
||||
@ -0,0 +1,206 @@
|
||||
# -*- coding: utf-8 -*-
|
||||
#
|
||||
# documentation build configuration file, created by
|
||||
# sphinx-quickstart on Sat Sep 27 13:23:22 2008-2009.
|
||||
#
|
||||
# This file is execfile()d with the current directory set to its
|
||||
# containing dir.
|
||||
#
|
||||
# The contents of this file are pickled, so don't put values in the namespace
|
||||
# that aren't pickleable (module imports are okay, they're removed
|
||||
# automatically).
|
||||
#
|
||||
# All configuration values have a default value; values that are commented out
|
||||
# serve to show the default value.
|
||||
|
||||
import sys
|
||||
import os
|
||||
|
||||
# If your extensions are in another directory, add it here. If the directory
|
||||
# is relative to the documentation root, use os.path.abspath to make it
|
||||
# absolute, like shown here.
|
||||
#sys.path.append(os.path.abspath('some/directory'))
|
||||
|
||||
sys.path.insert(0, os.path.join('ansible', 'lib'))
|
||||
sys.path.append(os.path.abspath('_themes'))
|
||||
|
||||
VERSION='0.01'
|
||||
AUTHOR='Michael DeHaan'
|
||||
|
||||
|
||||
# General configuration
|
||||
# ---------------------
|
||||
|
||||
# Add any Sphinx extension module names here, as strings.
|
||||
# They can be extensions
|
||||
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
|
||||
extensions = ['sphinx.ext.autodoc']
|
||||
|
||||
# Later on, add 'sphinx.ext.viewcode' to the list if you want to have
|
||||
# colorized code generated too for references.
|
||||
|
||||
|
||||
# Add any paths that contain templates here, relative to this directory.
|
||||
templates_path = ['.templates']
|
||||
|
||||
# The suffix of source filenames.
|
||||
source_suffix = '.rst'
|
||||
|
||||
# The master toctree document.
|
||||
master_doc = 'index'
|
||||
|
||||
# General substitutions.
|
||||
project = 'Ansible Documentation'
|
||||
copyright = "2012 Michael DeHaan"
|
||||
|
||||
# The default replacements for |version| and |release|, also used in various
|
||||
# other places throughout the built documents.
|
||||
#
|
||||
# The short X.Y version.
|
||||
version = VERSION
|
||||
# The full version, including alpha/beta/rc tags.
|
||||
release = VERSION
|
||||
|
||||
# There are two options for replacing |today|: either, you set today to some
|
||||
# non-false value, then it is used:
|
||||
#today = ''
|
||||
# Else, today_fmt is used as the format for a strftime call.
|
||||
today_fmt = '%B %d, %Y'
|
||||
|
||||
# List of documents that shouldn't be included in the build.
|
||||
#unused_docs = []
|
||||
|
||||
# List of directories, relative to source directories, that shouldn't be
|
||||
# searched for source files.
|
||||
#exclude_dirs = []
|
||||
|
||||
# A list of glob-style patterns that should be excluded when looking
|
||||
# for source files.
|
||||
exclude_patterns = ['modules']
|
||||
|
||||
# The reST default role (used for this markup: `text`) to use for all
|
||||
# documents.
|
||||
#default_role = None
|
||||
|
||||
# If true, '()' will be appended to :func: etc. cross-reference text.
|
||||
#add_function_parentheses = True
|
||||
|
||||
# If true, the current module name will be prepended to all description
|
||||
# unit titles (such as .. function::).
|
||||
#add_module_names = True
|
||||
|
||||
# If true, sectionauthor and moduleauthor directives will be shown in the
|
||||
# output. They are ignored by default.
|
||||
#show_authors = False
|
||||
|
||||
# The name of the Pygments (syntax highlighting) style to use.
|
||||
pygments_style = 'sphinx'
|
||||
|
||||
|
||||
# Options for HTML output
|
||||
# -----------------------
|
||||
|
||||
html_theme_path = ['_themes']
|
||||
html_theme = 'bootstrap'
|
||||
html_short_title = 'Ansible Documentation'
|
||||
|
||||
# The style sheet to use for HTML and HTML Help pages. A file of that name
|
||||
# must exist either in Sphinx' static/ path, or in one of the custom paths
|
||||
# given in html_static_path.
|
||||
html_style = 'default.css'
|
||||
|
||||
# The name for this set of Sphinx documents. If None, it defaults to
|
||||
# "<project> v<release> documentation".
|
||||
html_title = 'Ansible Documentation'
|
||||
|
||||
# A shorter title for the navigation bar. Default is the same as html_title.
|
||||
#html_short_title = None
|
||||
|
||||
# The name of an image file (within the static path) to place at the top of
|
||||
# the sidebar.
|
||||
#html_logo = None
|
||||
|
||||
# The name of an image file (within the static path) to use as favicon of the
|
||||
# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
|
||||
# pixels large.
|
||||
html_favicon = 'favicon.ico'
|
||||
|
||||
# Add any paths that contain custom static files (such as style sheets) here,
|
||||
# relative to this directory. They are copied after the builtin static files,
|
||||
# so a file named "default.css" will overwrite the builtin "default.css".
|
||||
#html_static_path = ['.static']
|
||||
|
||||
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
|
||||
# using the given strftime format.
|
||||
html_last_updated_fmt = '%b %d, %Y'
|
||||
|
||||
# If true, SmartyPants will be used to convert quotes and dashes to
|
||||
# typographically correct entities.
|
||||
#html_use_smartypants = True
|
||||
|
||||
# Custom sidebar templates, maps document names to template names.
|
||||
#html_sidebars = {}
|
||||
|
||||
# Additional templates that should be rendered to pages, maps page names to
|
||||
# template names.
|
||||
#html_additional_pages = {}
|
||||
|
||||
# If false, no module index is generated.
|
||||
#html_use_modindex = True
|
||||
|
||||
# If false, no index is generated.
|
||||
#html_use_index = True
|
||||
|
||||
# If true, the index is split into individual pages for each letter.
|
||||
#html_split_index = False
|
||||
|
||||
# If true, the reST sources are included in the HTML build as _sources/<name>.
|
||||
html_copy_source = False
|
||||
|
||||
# If true, an OpenSearch description file will be output, and all pages will
|
||||
# contain a <link> tag referring to it. The value of this option must be the
|
||||
# base URL from which the finished HTML is served.
|
||||
#html_use_opensearch = ''
|
||||
|
||||
# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml").
|
||||
#html_file_suffix = ''
|
||||
|
||||
# Output file base name for HTML help builder.
|
||||
htmlhelp_basename = 'Poseidodoc'
|
||||
|
||||
|
||||
# Options for LaTeX output
|
||||
# ------------------------
|
||||
|
||||
# The paper size ('letter' or 'a4').
|
||||
#latex_paper_size = 'letter'
|
||||
|
||||
# The font size ('10pt', '11pt' or '12pt').
|
||||
#latex_font_size = '10pt'
|
||||
|
||||
# Grouping the document tree into LaTeX files. List of tuples
|
||||
# (source start file, target name, title, author, document class
|
||||
# [howto/manual]).
|
||||
latex_documents = [
|
||||
('index', 'ansible.tex', 'Ansible Documentation',
|
||||
AUTHOR, 'manual'),
|
||||
]
|
||||
|
||||
# The name of an image file (relative to this directory) to place at the top of
|
||||
# the title page.
|
||||
#latex_logo = None
|
||||
|
||||
# For "manual" documents, if this is true, then toplevel headings are parts,
|
||||
# not chapters.
|
||||
#latex_use_parts = False
|
||||
|
||||
# Additional stuff for the LaTeX preamble.
|
||||
#latex_preamble = ''
|
||||
|
||||
# Documents to append as an appendix to all manuals.
|
||||
#latex_appendices = []
|
||||
|
||||
# If false, no module index is generated.
|
||||
#latex_use_modindex = True
|
||||
|
||||
autoclass_content = 'both'
|
||||
@ -0,0 +1,454 @@
|
||||
|
||||
<!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 And Next Steps — Ansible Documentation</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="shortcut icon" href="_static/favicon.ico"/>
|
||||
<link rel="top" title="Ansible Documentation" href="index.html" />
|
||||
<link rel="next" title="Ansible Modules" href="modules.html" />
|
||||
<link rel="prev" title="Inventory & Patterns" 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>
|
||||
|
||||
<script type="text/javascript">
|
||||
(function() {
|
||||
var po = document.createElement('script'); po.type = 'text/javascript'; po.async = true;
|
||||
po.src = 'https://apis.google.com/js/plusone.js';
|
||||
var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(po, s);
|
||||
})();
|
||||
</script>
|
||||
|
||||
<script>(function(d, s, id) {
|
||||
var js, fjs = d.getElementsByTagName(s)[0];
|
||||
if (d.getElementById(id)) return;
|
||||
js = d.createElement(s); js.id = id;
|
||||
js.src = "//connect.facebook.net/en_US/all.js#xfbml=1";
|
||||
fjs.parentNode.insertBefore(js, fjs);
|
||||
}(document, 'script', 'facebook-jssdk'));</script>
|
||||
|
||||
</head>
|
||||
<body>
|
||||
<div class="topbar" data-scrollspy="scrollspy" >
|
||||
<div class="topbar-inner">
|
||||
<div class="container">
|
||||
<a class="brand" href="index.html">Ansible Documentation</a>
|
||||
<ul class="nav">
|
||||
|
||||
<li><a href="/">Home</A>
|
||||
<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">Getting Started</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="patterns.html">Inventory & Patterns</a></li>
|
||||
<li class="toctree-l1 current"><a class="current reference internal" href="">Command Line Examples And Next Steps</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="playbooks2.html">Advanced Playbooks</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="bestpractices.html">Best Practices</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="api.html">API & Integrations</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="moduledev.html">Module Development</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 And Next Steps</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">File Transfer</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>
|
||||
<li><a class="reference internal" href="#limiting-selected-hosts">Limiting Selected Hosts</a></li>
|
||||
<li><a class="reference internal" href="#configuration-defaults">Configuration & Defaults</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-and-next-steps">
|
||||
<h1><a class="toc-backref" href="#contents">Command Line Examples And Next Steps</a><a class="headerlink" href="#command-line-examples-and-next-steps" 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’ll want to pick up on
|
||||
using <cite>/usr/bin/ansible-playbook</cite> – 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="contents topic" id="contents">
|
||||
<p class="topic-title first">Contents</p>
|
||||
<ul class="simple">
|
||||
<li><a class="reference internal" href="#command-line-examples-and-next-steps" id="id1">Command Line Examples And Next Steps</a><ul>
|
||||
<li><a class="reference internal" href="#parallelism-and-shell-commands" id="id2">Parallelism and Shell Commands</a></li>
|
||||
<li><a class="reference internal" href="#file-transfer" id="id3">File Transfer</a></li>
|
||||
<li><a class="reference internal" href="#managing-packages" id="id4">Managing Packages</a></li>
|
||||
<li><a class="reference internal" href="#users-and-groups" id="id5">Users and Groups</a></li>
|
||||
<li><a class="reference internal" href="#deploying-from-source-control" id="id6">Deploying From Source Control</a></li>
|
||||
<li><a class="reference internal" href="#managing-services" id="id7">Managing Services</a></li>
|
||||
<li><a class="reference internal" href="#time-limited-background-operations" id="id8">Time Limited Background Operations</a></li>
|
||||
<li><a class="reference internal" href="#limiting-selected-hosts" id="id9">Limiting Selected Hosts</a></li>
|
||||
<li><a class="reference internal" href="#configuration-defaults" id="id10">Configuration & Defaults</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
</ul>
|
||||
</div>
|
||||
<div class="section" id="parallelism-and-shell-commands">
|
||||
<h2><a class="toc-backref" href="#contents">Parallelism and Shell Commands</a><a class="headerlink" href="#parallelism-and-shell-commands" title="Permalink to this headline">¶</a></h2>
|
||||
<p>Let’s use ansible’s command line tool to reboot all web servers in Atlanta, 10 at a time. First, let’s
|
||||
set up SSH-agent so it can remember our credentials:</p>
|
||||
<div class="highlight-bash"><div class="highlight"><pre><span class="nv">$ </span>ssh-agent bash
|
||||
<span class="nv">$ </span>ssh-add ~/.ssh/id_rsa.pub
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>If you don’t want to use ssh-agent and want to instead SSH with a
|
||||
password instead of keys, you can with <tt class="docutils literal"><span class="pre">--ask-pass</span></tt> (<tt class="docutils literal"><span class="pre">-k</span></tt>), 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,
|
||||
<em>atlanta</em>, in 10 parallel forks:</p>
|
||||
<div class="highlight-bash"><div class="highlight"><pre><span class="nv">$ </span>ansible atlanta -a <span class="s2">"/sbin/reboot"</span> -f 10
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>In 0.7 and later, this will default to running from your user account. If you do not like this
|
||||
behavior, pass in “-u username”. (In 0.6 and before, it defaulted to root. Most folks prefered
|
||||
defaulting to the current user, so we changed it).</p>
|
||||
<p>If you want to run commands as a different user, it looks like this:</p>
|
||||
<div class="highlight-bash"><div class="highlight"><pre><span class="nv">$ </span>ansible atlanta -a <span class="s2">"/usr/bin/foo"</span> -u username
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>If you want to run commands through sudo:</p>
|
||||
<div class="highlight-bash"><div class="highlight"><pre><span class="nv">$ </span>ansible atlanta -a <span class="s2">"/usr/bin/foo"</span> -u username --sudo <span class="o">[</span>--ask-sudo-pass<span class="o">]</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>Use <tt class="docutils literal"><span class="pre">--ask-sudo-pass</span></tt> (<tt class="docutils literal"><span class="pre">-K</span></tt>) 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
|
||||
<tt class="docutils literal"><span class="pre">--sudo-user</span></tt> (<tt class="docutils literal"><span class="pre">-U</span></tt>):</p>
|
||||
<div class="highlight-bash"><div class="highlight"><pre><span class="nv">$ </span>ansible atlanta -a <span class="s2">"/usr/bin/foo"</span> -u username -U otheruser <span class="o">[</span>--ask-sudo-pass<span class="o">]</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>Ok, so those are basics. If you didn’t read about patterns and groups yet, go back and read <a class="reference internal" href="patterns.html"><em>Inventory & Patterns</em></a>.</p>
|
||||
<p>The <tt class="docutils literal"><span class="pre">-f</span> <span class="pre">10</span></tt> in the above specifies the usage of 10 simultaneous
|
||||
processes. Normally commands also take a <tt class="docutils literal"><span class="pre">-m</span></tt> for module name, but
|
||||
the default module name is ‘command’, so we didn’t need to
|
||||
specify that all of the time. We’ll use <tt class="docutils literal"><span class="pre">-m</span></tt> in later examples to
|
||||
run some other <a class="reference internal" href="modules.html"><em>Ansible Modules</em></a>.</p>
|
||||
<div class="admonition note">
|
||||
<p class="first admonition-title">Note</p>
|
||||
<p class="last">The <a class="reference internal" href="modules.html#command"><em>command</em></a> module requires absolute paths and does not
|
||||
support shell variables. If we want to execute a module using a
|
||||
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.</p>
|
||||
</div>
|
||||
<p>Using the <a class="reference internal" href="modules.html#shell"><em>shell</em></a> module looks like this:</p>
|
||||
<div class="highlight-bash"><div class="highlight"><pre><span class="nv">$ </span>ansible raleigh -m shell -a <span class="s1">'echo $TERM'</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>When running any command with the ansible <em>ad hoc</em> CLI (as opposed to
|
||||
<a class="reference internal" href="playbooks.html"><em>Playbooks</em></a>), pay particular attention to shell quoting rules, so
|
||||
the shell doesn’t eat a variable before it gets passed to Ansible.
|
||||
For example, using double vs single quotes in the above example would
|
||||
evaluate the variable on the box you were on.</p>
|
||||
<p>So far we’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 ‘idempotence’, and is a core design goal of ansible.
|
||||
However, we also recognize that running <em>ad hoc</em> commands is equally important, so Ansible easily supports both.</p>
|
||||
</div>
|
||||
<div class="section" id="file-transfer">
|
||||
<h2><a class="toc-backref" href="#contents">File Transfer</a><a class="headerlink" href="#file-transfer" title="Permalink to this headline">¶</a></h2>
|
||||
<p>Here’s another use case for the <cite>/usr/bin/ansible</cite> command line. Ansible can SCP lots of files to multiple machines in parallel.</p>
|
||||
<p>To transfer a file directly to many different servers:</p>
|
||||
<div class="highlight-bash"><div class="highlight"><pre><span class="nv">$ </span>ansible atlanta -m copy -a <span class="s2">"src=/etc/hosts dest=/tmp/hosts"</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>If you use playbooks, you can also take advantage of the <tt class="docutils literal"><span class="pre">template</span></tt> module,
|
||||
which takes this another step further. (See module and playbook documentation).</p>
|
||||
<p>The <tt class="docutils literal"><span class="pre">file</span></tt> module allows changing ownership and permissions on files. These
|
||||
same options can be passed directly to the <tt class="docutils literal"><span class="pre">copy</span></tt> module as well:</p>
|
||||
<div class="highlight-bash"><div class="highlight"><pre><span class="nv">$ </span>ansible webservers -m file -a <span class="s2">"dest=/srv/foo/a.txt mode=600"</span>
|
||||
<span class="nv">$ </span>ansible webservers -m file -a <span class="s2">"dest=/srv/foo/b.txt mode=600 owner=mdehaan group=mdehaan"</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>The <tt class="docutils literal"><span class="pre">file</span></tt> module can also create directories, similar to <tt class="docutils literal"><span class="pre">mkdir</span> <span class="pre">-p</span></tt>:</p>
|
||||
<div class="highlight-bash"><div class="highlight"><pre><span class="nv">$ </span>ansible webservers -m file -a <span class="s2">"dest=/path/to/c mode=644 owner=mdehaan group=mdehaan state=directory"</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>As well as delete directories (recursively) and delete files:</p>
|
||||
<div class="highlight-bash"><div class="highlight"><pre><span class="nv">$ </span>ansible webservers -m file -a <span class="s2">"dest=/path/to/c state=absent"</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
</div>
|
||||
<div class="section" id="managing-packages">
|
||||
<h2><a class="toc-backref" href="#contents">Managing Packages</a><a class="headerlink" href="#managing-packages" title="Permalink to this headline">¶</a></h2>
|
||||
<p>There are modules available for yum and apt. Here are some examples
|
||||
with yum.</p>
|
||||
<p>Ensure a package is installed, but don’t update it:</p>
|
||||
<div class="highlight-bash"><div class="highlight"><pre><span class="nv">$ </span>ansible webservers -m yum -a <span class="s2">"pkg=acme state=installed"</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>Ensure a package is installed to a specific version:</p>
|
||||
<div class="highlight-bash"><div class="highlight"><pre><span class="nv">$ </span>ansible webservers -m yum -a <span class="s2">"pkg=acme-1.5 state=installed"</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>Ensure a package is at the latest version:</p>
|
||||
<div class="highlight-bash"><div class="highlight"><pre><span class="nv">$ </span>ansible webservers -m yum -a <span class="s2">"pkg=acme state=latest"</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>Ensure a package is not installed:</p>
|
||||
<div class="highlight-bash"><div class="highlight"><pre><span class="nv">$ </span>ansible webservers -m yum -a <span class="s2">"pkg=acme state=removed"</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>Currently Ansible only has modules for managing packages with yum and apt. 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><a class="toc-backref" href="#contents">Users and Groups</a><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-bash"><div class="highlight"><pre><span class="nv">$ </span>ansible all -m user -a <span class="s2">"name=foo password=<crypted password here>"</span>
|
||||
|
||||
<span class="nv">$ </span>ansible all -m user -a <span class="s2">"name=foo state=absent"</span>
|
||||
</pre></div>
|
||||
</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, including
|
||||
how to manipulate groups and group membership.</p>
|
||||
</div>
|
||||
<div class="section" id="deploying-from-source-control">
|
||||
<h2><a class="toc-backref" href="#contents">Deploying From Source Control</a><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-bash"><div class="highlight"><pre><span class="nv">$ </span>ansible webservers -m git -a <span class="s2">"repo=git://foo.example.org/repo.git dest=/srv/myapp version=HEAD"</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>Since ansible modules can notify change handlers 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><a class="toc-backref" href="#contents">Managing Services</a><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-bash"><div class="highlight"><pre><span class="nv">$ </span>ansible webservers -m service -a <span class="s2">"name=httpd state=started"</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>Alternatively, restart a service on all webservers:</p>
|
||||
<div class="highlight-bash"><div class="highlight"><pre><span class="nv">$ </span>ansible webservers -m service -a <span class="s2">"name=httpd state=restarted"</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>Ensure a service is stopped:</p>
|
||||
<div class="highlight-bash"><div class="highlight"><pre><span class="nv">$ </span>ansible webservers -m service -a <span class="s2">"name=httpd state=stopped"</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
</div>
|
||||
<div class="section" id="time-limited-background-operations">
|
||||
<h2><a class="toc-backref" href="#contents">Time Limited Background Operations</a><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’t lose track. If you kick hosts and don’t want
|
||||
to poll, it looks like this:</p>
|
||||
<div class="highlight-bash"><div class="highlight"><pre><span class="nv">$ </span>ansible all -B 3600 -a <span class="s2">"/usr/bin/long_running_operation --do-stuff"</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>If you do decide you want to check on the job status later, you can:</p>
|
||||
<div class="highlight-bash"><div class="highlight"><pre><span class="nv">$ </span>ansible all -m async_status -a <span class="s2">"jid=123456789"</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>Polling is built-in and looks like this:</p>
|
||||
<div class="highlight-bash"><div class="highlight"><pre><span class="nv">$ </span>ansible all -B 1800 -P 60 -a <span class="s2">"/usr/bin/long_running_operation --do-stuff"</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>The above example says “run for 30 minutes max (<tt class="docutils literal"><span class="pre">-B</span></tt>: 30*60=1800),
|
||||
poll for status (<tt class="docutils literal"><span class="pre">-P</span></tt>) every 60 seconds”.</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 <tt class="docutils literal"><span class="pre">--forks</span></tt> 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>Typically you’ll be only be backgrounding long-running
|
||||
shell commands or software upgrades only. Backgrounding the copy module does not do a background file transfer. <a class="reference internal" href="playbooks.html"><em>Playbooks</em></a> also support polling, and have a simplified syntax for this.</p>
|
||||
</div>
|
||||
<div class="section" id="limiting-selected-hosts">
|
||||
<h2><a class="toc-backref" href="#contents">Limiting Selected Hosts</a><a class="headerlink" href="#limiting-selected-hosts" title="Permalink to this headline">¶</a></h2>
|
||||
<p class="versionadded">
|
||||
<span class="versionmodified">New in version 0.7.</span></p>
|
||||
<p>What hosts you select to manage can be additionally constrained by using the ‘–limit’ parameter or
|
||||
by using ‘batch’ (or ‘range’) selectors.</p>
|
||||
<p>As mentioned above, patterns can be strung together to select hosts in more than one group:</p>
|
||||
<div class="highlight-bash"><div class="highlight"><pre><span class="nv">$ </span>ansible webservers:dbservers -m <span class="nb">command</span> -a <span class="s2">"/bin/foo xyz"</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>This is an “or” condition. If you want to further constrain the selection, use –limit, which
|
||||
also works with <tt class="docutils literal"><span class="pre">ansible-playbook</span></tt>:</p>
|
||||
<div class="highlight-bash"><div class="highlight"><pre><span class="nv">$ </span>ansible webservers:dbservers -m <span class="nb">command</span> -a <span class="s2">"/bin/foo xyz"</span> region
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>Now let’s talk about range selection. Suppose you have 1000 servers in group ‘datacenter’, but only want to target one at a time. This is also easy:</p>
|
||||
<div class="highlight-bash"><div class="highlight"><pre><span class="nv">$ </span>ansible webservers<span class="o">[</span>0-99<span class="o">]</span> -m <span class="nb">command</span> -a <span class="s2">"/bin/foo xyz"</span>
|
||||
<span class="nv">$ </span>ansible webservers<span class="o">[</span>100-199<span class="o">]</span> -m <span class="nb">command</span> -a <span class="s2">"/bin/foo xyz"</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>This will select the first 100, then the second 100, host entries in the webservers group. (It does not matter
|
||||
what their names or IP addresses are).</p>
|
||||
<p>Both of these methods can be used at the same time, and ranges can also be passed to the –limit parameter.</p>
|
||||
</div>
|
||||
<div class="section" id="configuration-defaults">
|
||||
<h2><a class="toc-backref" href="#contents">Configuration & Defaults</a><a class="headerlink" href="#configuration-defaults" title="Permalink to this headline">¶</a></h2>
|
||||
<p class="versionadded">
|
||||
<span class="versionmodified">New in version 0.7.</span></p>
|
||||
<p>Ansible has an optional configuration file that can be used to tune settings and also eliminate the need to pass various command line flags. Ansible will look for the config file in the following order, using
|
||||
the first config file it finds present:</p>
|
||||
<ol class="arabic simple">
|
||||
<li>File specified by the <tt class="docutils literal"><span class="pre">ANSIBLE_CONFIG</span></tt> environment variable</li>
|
||||
<li><tt class="docutils literal"><span class="pre">ansible.cfg</span></tt> in the current working directory. (version 0.8 and up)</li>
|
||||
<li><tt class="docutils literal"><span class="pre">~/.ansible.cfg</span></tt></li>
|
||||
<li><tt class="docutils literal"><span class="pre">/etc/ansible/ansible.cfg</span></tt></li>
|
||||
</ol>
|
||||
<p>For those running from source, a sample configuration file lives in the examples/ directory. The RPM will install configuration into /etc/ansible/ansible.cfg automatically.</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 & 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>
|
||||
|
||||
|
||||
<br/>
|
||||
</div>
|
||||
<footer class="footer">
|
||||
<div class="container">
|
||||
<p>
|
||||
<p>
|
||||
© Copyright 2012 Michael DeHaan.<br/>
|
||||
Last updated on Oct 08, 2012.<br/>
|
||||
</p>
|
||||
</div>
|
||||
</footer>
|
||||
</body>
|
||||
</html>
|
||||
@ -0,0 +1,193 @@
|
||||
|
||||
|
||||
|
||||
<!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>Index — Ansible Documentation</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="shortcut icon" href="_static/favicon.ico"/>
|
||||
<link rel="top" title="Ansible Documentation" href="index.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>
|
||||
|
||||
<script type="text/javascript">
|
||||
(function() {
|
||||
var po = document.createElement('script'); po.type = 'text/javascript'; po.async = true;
|
||||
po.src = 'https://apis.google.com/js/plusone.js';
|
||||
var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(po, s);
|
||||
})();
|
||||
</script>
|
||||
|
||||
<script>(function(d, s, id) {
|
||||
var js, fjs = d.getElementsByTagName(s)[0];
|
||||
if (d.getElementById(id)) return;
|
||||
js = d.createElement(s); js.id = id;
|
||||
js.src = "//connect.facebook.net/en_US/all.js#xfbml=1";
|
||||
fjs.parentNode.insertBefore(js, fjs);
|
||||
}(document, 'script', 'facebook-jssdk'));</script>
|
||||
|
||||
</head>
|
||||
<body>
|
||||
<div class="topbar" data-scrollspy="scrollspy" >
|
||||
<div class="topbar-inner">
|
||||
<div class="container">
|
||||
<a class="brand" href="index.html">Ansible Documentation</a>
|
||||
<ul class="nav">
|
||||
|
||||
<li><a href="/">Home</A>
|
||||
<li class="dropdown" data-dropdown="dropdown">
|
||||
<a href="index.html"
|
||||
class="dropdown-toggle">Chapter</a>
|
||||
<span class="globaltoc"><ul>
|
||||
<li class="toctree-l1"><a class="reference internal" href="gettingstarted.html">Getting Started</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="patterns.html">Inventory & Patterns</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="examples.html">Command Line Examples And Next Steps</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="playbooks2.html">Advanced Playbooks</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="bestpractices.html">Best Practices</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="api.html">API & Integrations</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="moduledev.html">Module Development</a></li>
|
||||
</ul>
|
||||
</span>
|
||||
</li>
|
||||
<li class="dropdown" data-dropdown="dropdown">
|
||||
<a href="#"
|
||||
class="dropdown-toggle">Page</a>
|
||||
<span class="localtoc"></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">
|
||||
|
||||
|
||||
<h1 id="index">Index</h1>
|
||||
|
||||
<div class="genindex-jumpbox">
|
||||
|
||||
</div>
|
||||
|
||||
|
||||
<br/>
|
||||
</div>
|
||||
<footer class="footer">
|
||||
<div class="container">
|
||||
<p>
|
||||
<p>
|
||||
© Copyright 2012 Michael DeHaan.<br/>
|
||||
Last updated on Oct 08, 2012.<br/>
|
||||
</p>
|
||||
</div>
|
||||
</footer>
|
||||
</body>
|
||||
</html>
|
||||
@ -0,0 +1,411 @@
|
||||
|
||||
<!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>Getting Started — Ansible Documentation</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="shortcut icon" href="_static/favicon.ico"/>
|
||||
<link rel="top" title="Ansible Documentation" href="index.html" />
|
||||
<link rel="next" title="Inventory & Patterns" href="patterns.html" />
|
||||
<link rel="prev" title="Contents" href="index.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>
|
||||
|
||||
<script type="text/javascript">
|
||||
(function() {
|
||||
var po = document.createElement('script'); po.type = 'text/javascript'; po.async = true;
|
||||
po.src = 'https://apis.google.com/js/plusone.js';
|
||||
var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(po, s);
|
||||
})();
|
||||
</script>
|
||||
|
||||
<script>(function(d, s, id) {
|
||||
var js, fjs = d.getElementsByTagName(s)[0];
|
||||
if (d.getElementById(id)) return;
|
||||
js = d.createElement(s); js.id = id;
|
||||
js.src = "//connect.facebook.net/en_US/all.js#xfbml=1";
|
||||
fjs.parentNode.insertBefore(js, fjs);
|
||||
}(document, 'script', 'facebook-jssdk'));</script>
|
||||
|
||||
</head>
|
||||
<body>
|
||||
<div class="topbar" data-scrollspy="scrollspy" >
|
||||
<div class="topbar-inner">
|
||||
<div class="container">
|
||||
<a class="brand" href="index.html">Ansible Documentation</a>
|
||||
<ul class="nav">
|
||||
|
||||
<li><a href="/">Home</A>
|
||||
<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 current"><a class="current reference internal" href="">Getting Started</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="patterns.html">Inventory & Patterns</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="examples.html">Command Line Examples And Next Steps</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="playbooks2.html">Advanced Playbooks</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="bestpractices.html">Best Practices</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="api.html">API & Integrations</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="moduledev.html">Module Development</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="#">Getting Started</a><ul>
|
||||
<li><a class="reference internal" href="#requirements">Requirements</a></li>
|
||||
<li><a class="reference internal" href="#python-2-6-epel-instructions-for-rhel-and-centos-5">Python 2.6 EPEL instructions for RHEL and CentOS 5</a></li>
|
||||
<li><a class="reference internal" href="#getting-ansible">Getting Ansible</a><ul>
|
||||
<li><a class="reference internal" href="#running-from-checkout">Running From Checkout</a></li>
|
||||
<li><a class="reference internal" href="#make-install">Make Install</a></li>
|
||||
<li><a class="reference internal" href="#via-rpm">Via RPM</a></li>
|
||||
<li><a class="reference internal" href="#debian-gentoo-arch-others">Debian, Gentoo, Arch, Others</a></li>
|
||||
<li><a class="reference internal" href="#tagged-releases">Tagged Releases</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><a class="reference internal" href="#choosing-between-paramiko-and-native-ssh">Choosing Between Paramiko and Native SSH</a></li>
|
||||
<li><a class="reference internal" href="#your-first-commands">Your first commands</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="getting-started">
|
||||
<h1><a class="toc-backref" href="#contents">Getting Started</a><a class="headerlink" href="#getting-started" title="Permalink to this headline">¶</a></h1>
|
||||
<div class="contents topic" id="contents">
|
||||
<p class="topic-title first">Contents</p>
|
||||
<ul class="simple">
|
||||
<li><a class="reference internal" href="#getting-started" id="id1">Getting Started</a><ul>
|
||||
<li><a class="reference internal" href="#requirements" id="id2">Requirements</a></li>
|
||||
<li><a class="reference internal" href="#python-2-6-epel-instructions-for-rhel-and-centos-5" id="id3">Python 2.6 EPEL instructions for RHEL and CentOS 5</a></li>
|
||||
<li><a class="reference internal" href="#getting-ansible" id="id4">Getting Ansible</a></li>
|
||||
<li><a class="reference internal" href="#choosing-between-paramiko-and-native-ssh" id="id5">Choosing Between Paramiko and Native SSH</a></li>
|
||||
<li><a class="reference internal" href="#your-first-commands" id="id6">Your first commands</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
</ul>
|
||||
</div>
|
||||
<div class="section" id="requirements">
|
||||
<h2><a class="toc-backref" href="#contents">Requirements</a><a class="headerlink" href="#requirements" title="Permalink to this headline">¶</a></h2>
|
||||
<p>Requirements for Ansible are extremely minimal.</p>
|
||||
<p>Ansible is written for Python 2.6. If you are running Python 2.5 on an “Enterprise Linux” variant,
|
||||
your distribution can easily install 2.6 (see instructions in the next section). Newer versions
|
||||
of Linux and OS X should already have 2.6.</p>
|
||||
<p>In additon to Python 2.6, you will want the following packages:</p>
|
||||
<ul class="simple">
|
||||
<li><tt class="docutils literal"><span class="pre">paramiko</span></tt></li>
|
||||
<li><tt class="docutils literal"><span class="pre">PyYAML</span></tt></li>
|
||||
<li><tt class="docutils literal"><span class="pre">python-jinja2</span></tt></li>
|
||||
</ul>
|
||||
<p>On the managed nodes, you only need Python 2.4 or later, but if you are are running less than Python 2.6 on them, you will
|
||||
also need:</p>
|
||||
<ul class="simple">
|
||||
<li><tt class="docutils literal"><span class="pre">python-simplejson</span></tt></li>
|
||||
</ul>
|
||||
<div class="admonition note">
|
||||
<p class="first admonition-title">Note</p>
|
||||
<p class="last">Ansible’s “raw” module (for executing commands in a quick and dirty
|
||||
way) and the copy module – some of the most basic features in
|
||||
ansible – don’t even need that. So technically, you can use
|
||||
Ansible to install python-simplejson using the raw module, which
|
||||
then allows you to use everything else. (That’s jumping ahead
|
||||
though.)</p>
|
||||
</div>
|
||||
</div>
|
||||
<div class="section" id="python-2-6-epel-instructions-for-rhel-and-centos-5">
|
||||
<h2><a class="toc-backref" href="#contents">Python 2.6 EPEL instructions for RHEL and CentOS 5</a><a class="headerlink" href="#python-2-6-epel-instructions-for-rhel-and-centos-5" title="Permalink to this headline">¶</a></h2>
|
||||
<p>These distributions don’t have Python 2.6 by default, but it is easily
|
||||
installable. If you have not already done so, <a class="reference external" href="http://fedoraproject.org/wiki/EPEL">configure EPEL</a></p>
|
||||
<div class="highlight-bash"><div class="highlight"><pre><span class="nv">$ </span>yum install python26 python26-PyYAML python26-paramiko python26-jinja2
|
||||
</pre></div>
|
||||
</div>
|
||||
</div>
|
||||
<div class="section" id="getting-ansible">
|
||||
<h2><a class="toc-backref" href="#contents">Getting Ansible</a><a class="headerlink" href="#getting-ansible" title="Permalink to this headline">¶</a></h2>
|
||||
<p>If you are interested in using all the latest features, you may wish to keep up to date
|
||||
with the development branch of the git checkout. This also makes it easiest to contribute
|
||||
back to the project.</p>
|
||||
<p>Instructions for installing from source are below.</p>
|
||||
<p>Ansible’s release cycles are about one month long. Due to this
|
||||
short release cycle, any bugs will generally be fixed in the next release versus maintaining
|
||||
backports on the stable branch.</p>
|
||||
<p>You may also wish to follow the <a class="reference external" href="https://github.com/ansible/ansible">Github project</a> if
|
||||
you have a github account. This is also where we keep the issue tracker for sharing
|
||||
bugs and feature ideas.</p>
|
||||
<div class="section" id="running-from-checkout">
|
||||
<h3>Running From Checkout<a class="headerlink" href="#running-from-checkout" title="Permalink to this headline">¶</a></h3>
|
||||
<p>Ansible is trivially easy to run from a checkout, root permissions are not required
|
||||
to use it:</p>
|
||||
<div class="highlight-bash"><div class="highlight"><pre><span class="nv">$ </span>git clone git://github.com/ansible/ansible.git
|
||||
<span class="nv">$ </span><span class="nb">cd</span> ./ansible
|
||||
<span class="nv">$ </span><span class="nb">source</span> ./hacking/env-setup
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>You can optionally specify an inventory file (see <a class="reference internal" href="patterns.html"><em>Inventory & Patterns</em></a>) other than /etc/ansible/hosts:</p>
|
||||
<div class="highlight-bash"><div class="highlight"><pre><span class="nv">$ </span><span class="nb">echo</span> <span class="s2">"127.0.0.1"</span> > ~/ansible_hosts
|
||||
<span class="nv">$ </span><span class="nb">export </span><span class="nv">ANSIBLE_HOSTS</span><span class="o">=</span>~/ansible_hosts
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>Now let’s test things:</p>
|
||||
<div class="highlight-bash"><div class="highlight"><pre><span class="nv">$ </span>ansible all -m ping --ask-pass
|
||||
</pre></div>
|
||||
</div>
|
||||
</div>
|
||||
<div class="section" id="make-install">
|
||||
<h3>Make Install<a class="headerlink" href="#make-install" title="Permalink to this headline">¶</a></h3>
|
||||
<p>If you are not working from a distribution where Ansible is packaged yet, you can install Ansible
|
||||
using “make install”. This is done through <cite>python-distutils</cite>:</p>
|
||||
<div class="highlight-bash"><div class="highlight"><pre><span class="nv">$ </span>git clone git://github.com/ansible/ansible.git
|
||||
<span class="nv">$ </span><span class="nb">cd</span> ./ansible
|
||||
<span class="nv">$ </span>sudo make install
|
||||
</pre></div>
|
||||
</div>
|
||||
</div>
|
||||
<div class="section" id="via-rpm">
|
||||
<h3>Via RPM<a class="headerlink" href="#via-rpm" title="Permalink to this headline">¶</a></h3>
|
||||
<p>RPMs for the last Ansible release are available for <a class="reference external" href="http://fedoraproject.org/wiki/EPEL">EPEL</a> 6 and currently supported
|
||||
Fedora distributions. Ansible itself can manage earlier operating
|
||||
systems that contain python 2.4 or higher.</p>
|
||||
<div class="highlight-bash"><div class="highlight"><pre><span class="c"># install the epel-release RPM if needed on CentOS, RHEL, or Scientific Linux</span>
|
||||
<span class="nv">$ </span>sudo yum install ansible
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>You can also use the <tt class="docutils literal"><span class="pre">make</span> <span class="pre">rpm</span></tt> command to build an RPM you can
|
||||
distribute and install:</p>
|
||||
<div class="highlight-bash"><div class="highlight"><pre><span class="nv">$ </span>git clone git://github.com/ansible/ansible.git
|
||||
<span class="nv">$ </span><span class="nb">cd</span> ./ansible
|
||||
<span class="nv">$ </span>make rpm
|
||||
<span class="nv">$ </span>sudo rpm -Uvh ~/rpmbuild/ansible-*.noarch.rpm
|
||||
</pre></div>
|
||||
</div>
|
||||
</div>
|
||||
<div class="section" id="debian-gentoo-arch-others">
|
||||
<h3>Debian, Gentoo, Arch, Others<a class="headerlink" href="#debian-gentoo-arch-others" title="Permalink to this headline">¶</a></h3>
|
||||
<p>Ubuntu builds are available <a class="reference external" href="https://launchpad.net/~rquillo/+archive/ansible">in a PPA here</a></p>
|
||||
<p>Debian/Ubuntu package recipes can also be built from the source checkout, run:</p>
|
||||
<div class="highlight-bash"><div class="highlight"><pre><span class="nv">$ </span>make debian
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>Gentoo eBuilds are available <a class="reference external" href="https://github.com/uu/ubuilds">on github here</a></p>
|
||||
<p>An Arch PKGBUILD is available on <a class="reference external" href="https://aur.archlinux.org/packages.php?ID=58621">AUR</a>
|
||||
If you have python3 installed on Arch, you probably want to symlink python to python2:</p>
|
||||
<div class="highlight-bash"><div class="highlight"><pre><span class="nv">$ </span>sudo ln -sf /usr/bin/python2 /usr/bin/python
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>If you would like to package Ansible for Homebrew, BSD, or others,
|
||||
please stop by the mailing list and say hi!</p>
|
||||
</div>
|
||||
<div class="section" id="tagged-releases">
|
||||
<h3>Tagged Releases<a class="headerlink" href="#tagged-releases" title="Permalink to this headline">¶</a></h3>
|
||||
<p>Tagged releases are available as tar.gz files from the Ansible github
|
||||
project page:</p>
|
||||
<ul class="simple">
|
||||
<li><a class="reference external" href="https://github.com/ansible/ansible/downloads">Ansible/downloads</a></li>
|
||||
</ul>
|
||||
</div>
|
||||
</div>
|
||||
<div class="section" id="choosing-between-paramiko-and-native-ssh">
|
||||
<h2><a class="toc-backref" href="#contents">Choosing Between Paramiko and Native SSH</a><a class="headerlink" href="#choosing-between-paramiko-and-native-ssh" title="Permalink to this headline">¶</a></h2>
|
||||
<p>By default, ansible uses paramiko to talk to managed nodes over SSH. Paramiko is fast, works
|
||||
very transparently, requires no configuration, and is a good choice for most users.
|
||||
However, it does not support some advanced SSH features that folks will want to use.</p>
|
||||
<p class="versionadded">
|
||||
<span class="versionmodified">New in version 0.5.</span></p>
|
||||
<p>If you want to leverage more advanced SSH features (such as Kerberized
|
||||
SSH or jump hosts), pass the flag “–connection=ssh” to any ansible
|
||||
command, or set the ANSIBLE_TRANSPORT environment variable to
|
||||
‘ssh’. This will cause Ansible to use openssh tools instead.</p>
|
||||
<p>If ANSIBLE_SSH_ARGS are not set, ansible will try to use some sensible ControlMaster options
|
||||
by default. You are free to override this environment variable, but should still pass ControlMaster
|
||||
options to ensure performance of this transport. With ControlMaster in use, both transports
|
||||
are roughly the same speed. Without CM, the binary ssh transport is signficantly slower.</p>
|
||||
<p>If none of this makes sense to you, the default paramiko option is probably fine.</p>
|
||||
</div>
|
||||
<div class="section" id="your-first-commands">
|
||||
<h2><a class="toc-backref" href="#contents">Your first commands</a><a class="headerlink" href="#your-first-commands" title="Permalink to this headline">¶</a></h2>
|
||||
<p>Now that you’ve installed Ansible, it’s time to test it.</p>
|
||||
<p>Edit (or create) /etc/ansible/hosts and put one or more remote systems in it, for
|
||||
which you have your SSH key in <tt class="docutils literal"><span class="pre">authorized_keys</span></tt>:</p>
|
||||
<div class="highlight-python"><pre>192.168.1.50
|
||||
aserver.example.org
|
||||
bserver.example.org</pre>
|
||||
</div>
|
||||
<p>Set up SSH agent to avoid retyping passwords:</p>
|
||||
<div class="highlight-bash"><div class="highlight"><pre><span class="nv">$ </span>ssh-agent bash
|
||||
<span class="nv">$ </span>ssh-add ~/.ssh/id_rsa
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>(Depending on your setup, you may wish to ansible’s –private-key-file option to specify a pem file instead)</p>
|
||||
<p>Now ping all your nodes:</p>
|
||||
<div class="highlight-bash"><div class="highlight"><pre><span class="nv">$ </span>ansible all -m ping
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>In Ansible 0.7 and later, ansible will attempt to remote connect to the machines using your current
|
||||
user name, just like SSH would. In 0.6 and before, this actually defaults to ‘root’ (we liked the current
|
||||
user behavior better). To override the remote user name, just use the ‘-u’ parameter.</p>
|
||||
<p>If you would like to access sudo mode, there are also flags to do that:</p>
|
||||
<div class="highlight-bash"><div class="highlight"><pre><span class="c"># as bruce</span>
|
||||
<span class="nv">$ </span>ansible all -m ping -u bruce
|
||||
<span class="c"># as bruce, sudoing to root</span>
|
||||
<span class="nv">$ </span>ansible all -m ping -u bruce --sudo
|
||||
<span class="c"># as bruce, sudoing to batman</span>
|
||||
<span class="nv">$ </span>ansible all -m ping -u bruce --sudo --sudo-user batman
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>Now run a live command on all of your nodes:</p>
|
||||
<div class="highlight-bash"><div class="highlight"><pre><span class="nv">$ </span>ansible all -a <span class="s2">"/bin/echo hello"</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>Congratulations. You’ve just contacted your nodes with Ansible. It’s
|
||||
now time to read some of the more real-world <a class="reference internal" href="examples.html"><em>Command Line Examples And Next Steps</em></a>, and explore
|
||||
what you can do with different modules, as well as the Ansible
|
||||
<a class="reference internal" href="playbooks.html"><em>Playbooks</em></a> language. Ansible is not just about running commands, it
|
||||
also has powerful configuration management and deployment features. There’s more to
|
||||
explore, but you already have a fully working infrastructure!</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="examples.html"><em>Command Line Examples And Next Steps</em></a></dt>
|
||||
<dd>Examples of basic commands</dd>
|
||||
<dt><a class="reference internal" href="playbooks.html"><em>Playbooks</em></a></dt>
|
||||
<dd>Learning ansible’s configuration management language</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>
|
||||
|
||||
|
||||
<br/>
|
||||
</div>
|
||||
<footer class="footer">
|
||||
<div class="container">
|
||||
<p>
|
||||
<p>
|
||||
© Copyright 2012 Michael DeHaan.<br/>
|
||||
Last updated on Oct 08, 2012.<br/>
|
||||
</p>
|
||||
</div>
|
||||
</footer>
|
||||
</body>
|
||||
</html>
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 7.7 KiB |
@ -0,0 +1,269 @@
|
||||
|
||||
<!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>Glossary — Ansible - SSH-Based Configuration Management & 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="shortcut icon" href="_static/favicon.ico"/>
|
||||
<link rel="top" title="Ansible - SSH-Based Configuration Management & Deployment" href="index.html" />
|
||||
<link rel="next" title="Who Uses Ansible" href="who_uses_ansible.html" />
|
||||
<link rel="prev" title="FAQ" href="faq.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>
|
||||
|
||||
<script type="text/javascript">
|
||||
(function() {
|
||||
var po = document.createElement('script'); po.type = 'text/javascript'; po.async = true;
|
||||
po.src = 'https://apis.google.com/js/plusone.js';
|
||||
var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(po, s);
|
||||
})();
|
||||
</script>
|
||||
|
||||
<script>(function(d, s, id) {
|
||||
var js, fjs = d.getElementsByTagName(s)[0];
|
||||
if (d.getElementById(id)) return;
|
||||
js = d.createElement(s); js.id = id;
|
||||
js.src = "//connect.facebook.net/en_US/all.js#xfbml=1";
|
||||
fjs.parentNode.insertBefore(js, fjs);
|
||||
}(document, 'script', 'facebook-jssdk'));</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">Getting Started</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="patterns.html">Inventory & Patterns</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="examples.html">Command Line</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="playbooks2.html">Advanced Playbooks</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="bestpractices.html">Best Practices</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="api.html">API & Integrations</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="moduledev.html">Module Development</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="faq.html">FAQ</a></li>
|
||||
<li class="toctree-l1 current"><a class="current reference internal" href="">Glossary</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="who_uses_ansible.html">Who Uses Ansible</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="#">Glossary</a></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>
|
||||
<a href="http://github.com/ansible/ansible"><img style="position: absolute; right: 0; border: 0;" src="http://ansible.github.com/github.png" alt="Fork me on GitHub"></a>
|
||||
|
||||
|
||||
<div class="container">
|
||||
<a href="http://ansible.github.com"><img src="http://ansible.github.com/ansible-logo.png" alt="Ansible"/></a><br/>
|
||||
<br/>
|
||||
|
||||
<div class="section" id="glossary">
|
||||
<h1>Glossary<a class="headerlink" href="#glossary" title="Permalink to this headline">¶</a></h1>
|
||||
<p>After reading through the rest of the documentation, it may be helpful to review some terms.</p>
|
||||
<p>ansible – from science fiction, a device for communicating instanteously over large distances.</p>
|
||||
<p>ansible – When speaking of /usr/bin/ansible, a tool for ad-hoc task execution on a group of hosts. This constrasts with /usr/bin/ansible-playbook, which is a full on configuration management and orchestration tool built on top of these fundamentals. Both come with ‘ansible’, the application.</p>
|
||||
<p>action – the part of a task that specifies what module to run and what arguments to send it</p>
|
||||
<p>async – the act of running a ansible task in the background, potentially polling it for completion. This is useful for kicking off tasks where the result is not important, or in executing tasks that would exceed the SSH timeout.</p>
|
||||
<p>cobbler – a kickstart, mirroring, power management, and miscellaneous datacenter management tool that Michael wrote before Ansible, and is frequently used with it. See <a class="reference external" href="http://cobbler.github.com">Cobbler</a></p>
|
||||
<p>common module code – a facility in which Ansible modules written in Python can minimize boilerplate code for argument validation and returning values. This is not available to non-Python modules but modules can still be written in languages other than Python.</p>
|
||||
<p>connection – how Ansible connects to and manages remote hosts. Paramiko and native ssh are the main options, though
|
||||
there is also a local connection mode.</p>
|
||||
<p>cowsay – a special utility program that, if installed, greatly enhances the clarity of ansible-playbook output.</p>
|
||||
<p>daisy chaining – comes up in development discussions. It’s how in Ansible one module (like copy or template) can
|
||||
use parameters supported by the file module by requesting the file module be run after the copy module. For example, if specifying a file be templated, we can also specify the mode and owner because the file module is automatically daisy-chained
|
||||
after the file module.</p>
|
||||
<p>DSL – domain specific language. The idea of making a special “programming” language or a subset of a language to build a tool out of. Ansible doesn’t believe in these, and instead treats it’s playbook language as a data format.</p>
|
||||
<p>env-setup – a very useful script in the “hacking” directory of an ansible checkout. Sourcing this script makes it very easy to run ansible from source without doing any installation.</p>
|
||||
<p>external inventory script – the act of using an executable script in place of an ansible inventory file, so that ansible will invoke the script when needed to ask about what hosts it is managing and variables related to those hosts.</p>
|
||||
<p>fact – a variable discovered about a remote host, rather than configured in a config file. Facts can include
|
||||
the system architecture, the hostname, the operating system version, and so on. facts can be used in configuration
|
||||
files.</p>
|
||||
<p>forks – the level of parallelism used with a /usr/bin/ansible or /usr/bin/ansible-playbook command. Ansible executes multiple remote management commands in parallel to get things done faster.</p>
|
||||
<p>func – an earlier ad-hoc execution tool that is the basis of some of the ideas in Ansible. Michael wrote Func with some colleagues from Red Hat, and a later tool called taboot built on Func helped inspire the playbooks language. Func didn’t have a configuration management language on top of it, nor did it use SSH, but it helped pave the way for several other tools.</p>
|
||||
<p>handler – a special class of a task that is not run unless a given task registers a change event. Handlers are most
|
||||
frequently used for restarting services when the contents of configuration files change.</p>
|
||||
<p>idempotent – when applied to configuration management, this means that running a given task twice does not produce
|
||||
an unexpected effect on the system. Mathematically, F(x) = F(F(x)). Ansible’s core modules all support this concept
|
||||
but Ansible does not force this upon you.</p>
|
||||
<p>include – a playbook, handler, or variable data loaded from another file</p>
|
||||
<p>infrastructure as code – the practice of treating configuration, management, and deployment of systems as a software project. Ansible doesn’t really believe in this and tries to simplify things by making a simpler language that is easier to write and audit, and is therefore easier to understand by all parties involved. More advanced takes on I.A.C. use actual programming languages to describe configurations.</p>
|
||||
<p>inventory – ansible keeps track of what hosts you are managing, and allows them to be put in groups for easier selection. This file is by default in a simple INI format, but can be replaced with an ‘external inventory script’</p>
|
||||
<p>Jinja2 – Ansible uses this as a templating language for the ‘template’ module.</p>
|
||||
<p>JSON – the format Ansible modules use to return data over the wire. “Java Script Object Notation”</p>
|
||||
<p>module – a reusable unit of logic that tells Ansible how to do things on remote machines. Ansible ships with many modules written in Python, but modules can be written in any language. Modules return structured data in JSON.</p>
|
||||
<p>notify – what a task does when it detects that something has changed on the remote system. A task notifying a handler
|
||||
means it is sending a message to the handler that it needs to run at the end of a playbook execution.</p>
|
||||
<p>paramiko – the default connection type for ansible uses a pure-Python SSH library called paramiko. It is generally
|
||||
easier to set up than native SSH but does not offer as many configuration options and does not support Kerberized SSH.</p>
|
||||
<p>pattern – a selector that can match host or group names using wildcards. Patterns are used in plays or in ad-hoc executions of /usr/bin/ansible to target groups of hosts to manage.</p>
|
||||
<p>play – a group of ansible tasks that are to be executed on the same set of hosts. A play is always run by the same user account and may optionally sudo to a particular user after connecting. In addition to a list of tasks, a play may also choose to define variables or include them from other files, all of which are shared with each task in the play.</p>
|
||||
<p>playbook – a list of ansible plays grouped together in a single file, which are run top to bottom. Each play may select different hosts and have different tasks. A playbook is analogous to a Chef recipe, a Puppet manifest, a CFEngine “promise”. Playbooks can be broken up into more than one file using includes, in which case it’s still ok to call it a playbook.</p>
|
||||
<p>pull – the act of a managed system phoning home to ask how it is configured. This is useful in large scale out scenarios or for periodic automatic system remediation.</p>
|
||||
<p>push – the act of reaching out to systems you want to manage rather than them phoning home. This is Ansible’s default
|
||||
mode, but pull is also supported via the ‘ansible-pull’ script.</p>
|
||||
<p>runner – comes up in development discussions. a core component of the ansible code that runs a single module/task against a given set of hosts. /usr/bin/ansible makes use of runner directly. Playbooks instantiate multiple instances of runner,
|
||||
one for each task in a playbook.</p>
|
||||
<p>setup cache – comes up in development discussions. The setup cache is a mechanism of storing fact results from various
|
||||
systems and makes them available as variables in action lines and templates</p>
|
||||
<p>SSH – secure shell. Ansible by default uses SSH to talk to remote hosts because it is already there and very secure. It does not require any additional daemons.</p>
|
||||
<p>task – one of many ansible modules to execute on a given set of hosts, and the parameters to use when calling it.
|
||||
A task has a name, an ‘action’, and other optional variables. Making sure a package is installed, or a file
|
||||
is templated and transferred, is the example of a task.</p>
|
||||
<p>template – the act of taking a file with variable placeholders in it and substituting variables to make a final file. Templating is frequently used to place configuration files.</p>
|
||||
<p>test-module – a useful script in the “hacking” directory of an ansible checkout for running a module locally, without ansible’s core code in the way. Used when developing or debugging modules.</p>
|
||||
<p>Van Halen – the great American Rock Band, known for great instrumental guitar work and also songs about Alien Abductions. All Ansible releases are code named after Van Halen songs. C’mon Dave, gimme a break.</p>
|
||||
<p>YAML – the core language format for ansible playbooks and include files. Stands for “YAML Ain’t Markup Language”. YAML can be taken to extremes where it is difficult to write and read, but Ansible uses a relatively simple dialect and minimal levels of nesting.</p>
|
||||
</div>
|
||||
|
||||
|
||||
<br/>
|
||||
</div>
|
||||
<footer class="footer">
|
||||
|
||||
<div class="container">
|
||||
<div id="fb-root"></div>
|
||||
<p>
|
||||
<form action="https://www.paypal.com/cgi-bin/webscr" method="post">
|
||||
<input type="hidden" name="cmd" value="_donations">
|
||||
<input type="hidden" name="business" value="michael.dehaan@gmail.com">
|
||||
<input type="hidden" name="lc" value="US">
|
||||
<input type="hidden" name="item_name" value="Ansible">
|
||||
<input type="hidden" name="no_note" value="0">
|
||||
<input type="hidden" name="currency_code" value="USD">
|
||||
<input type="hidden" name="bn" value="PP-DonationsBF:btn_donate_LG.gif:NonHostedGuest">
|
||||
<input type="image" src="https://www.paypalobjects.com/en_US/i/btn/btn_donate_LG.gif" border="0" name="submit" alt="PayPal - The safer, easier way to pay online!">
|
||||
<img alt="" border="0" src="https://www.paypalobjects.com/en_US/i/scr/pixel.gif" width="1" height="1">
|
||||
</form>
|
||||
</p>
|
||||
<p>
|
||||
<a href="https://twitter.com/share" class="twitter-share-button" data-text="ansible.github.com">Share On Twitter</a>
|
||||
<script>!function(d,s,id){var js,fjs=d.getElementsByTagName(s)[0];if(!d.getElementById(id)){js=d.createElement(s);js.id=id;js.src="//platform.twitter.com/widgets.js";fjs.parentNode.insertBefore(js,fjs);}}(document,"script","twitter-wjs");</script>
|
||||
<g:plusone annotation="inline"></g:plusone>
|
||||
<div class="fb-like" data-href="http://ansible.github.com" data-send="true" data-width="450" data-show-faces="false"></div>
|
||||
</p>
|
||||
<p>
|
||||
© Copyright 2012 Michael DeHaan.<br/>
|
||||
Last updated on Aug 10, 2012.<br/>
|
||||
</p>
|
||||
</div>
|
||||
</footer>
|
||||
</body>
|
||||
</html>
|
||||
@ -0,0 +1,208 @@
|
||||
|
||||
<!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>Contents — Ansible Documentation</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="shortcut icon" href="_static/favicon.ico"/>
|
||||
<link rel="top" title="Ansible Documentation" href="#" />
|
||||
<link rel="next" title="Getting Started" href="gettingstarted.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>
|
||||
|
||||
<script type="text/javascript">
|
||||
(function() {
|
||||
var po = document.createElement('script'); po.type = 'text/javascript'; po.async = true;
|
||||
po.src = 'https://apis.google.com/js/plusone.js';
|
||||
var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(po, s);
|
||||
})();
|
||||
</script>
|
||||
|
||||
<script>(function(d, s, id) {
|
||||
var js, fjs = d.getElementsByTagName(s)[0];
|
||||
if (d.getElementById(id)) return;
|
||||
js = d.createElement(s); js.id = id;
|
||||
js.src = "//connect.facebook.net/en_US/all.js#xfbml=1";
|
||||
fjs.parentNode.insertBefore(js, fjs);
|
||||
}(document, 'script', 'facebook-jssdk'));</script>
|
||||
|
||||
</head>
|
||||
<body>
|
||||
<div class="topbar" data-scrollspy="scrollspy" >
|
||||
<div class="topbar-inner">
|
||||
<div class="container">
|
||||
<a class="brand" href="#">Ansible Documentation</a>
|
||||
<ul class="nav">
|
||||
|
||||
<li><a href="/">Home</A>
|
||||
<li class="dropdown" data-dropdown="dropdown">
|
||||
<a href="#"
|
||||
class="dropdown-toggle">Chapter</a>
|
||||
<span class="globaltoc"><ul>
|
||||
<li class="toctree-l1"><a class="reference internal" href="gettingstarted.html">Getting Started</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="patterns.html">Inventory & Patterns</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="examples.html">Command Line Examples And Next Steps</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="playbooks2.html">Advanced Playbooks</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="bestpractices.html">Best Practices</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="api.html">API & Integrations</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="moduledev.html">Module Development</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="#">Contents</a><ul>
|
||||
</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="contents">
|
||||
<h1>Contents<a class="headerlink" href="#contents" title="Permalink to this headline">¶</a></h1>
|
||||
<div class="toctree-wrapper compound">
|
||||
<ul>
|
||||
<li class="toctree-l1"><a class="reference internal" href="gettingstarted.html">Getting Started</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="patterns.html">Inventory & Patterns</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="examples.html">Command Line Examples And Next Steps</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="playbooks2.html">Advanced Playbooks</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="bestpractices.html">Best Practices</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="api.html">API & Integrations</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="moduledev.html">Module Development</a></li>
|
||||
</ul>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
|
||||
<br/>
|
||||
</div>
|
||||
<footer class="footer">
|
||||
<div class="container">
|
||||
<p>
|
||||
<p>
|
||||
© Copyright 2012 Michael DeHaan.<br/>
|
||||
Last updated on Oct 08, 2012.<br/>
|
||||
</p>
|
||||
</div>
|
||||
</footer>
|
||||
</body>
|
||||
</html>
|
||||
@ -0,0 +1,202 @@
|
||||
|
||||
<!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>Man Pages — Ansible - SSH-Based Configuration Management & 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="shortcut icon" href="_static/favicon.ico"/>
|
||||
<link rel="top" title="Ansible - SSH-Based Configuration Management & Deployment" href="index.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>
|
||||
<li class="toctree-l1"><a class="reference internal" href="gettingstarted.html">Downloads & 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"><a class="reference internal" href="examples.html">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 & 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>
|
||||
</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="#">Man Pages</a><ul>
|
||||
<li><a class="reference internal" href="#ansible-1">ansible(1)</a></li>
|
||||
<li><a class="reference internal" href="#ansible-playbook-1">ansible-playbook(1)</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="man-pages">
|
||||
<span id="man"></span><h1>Man Pages<a class="headerlink" href="#man-pages" title="Permalink to this headline">¶</a></h1>
|
||||
<p>Ansible’s man pages list available command line options. See the rest of the web site for
|
||||
examples of these tools in use.</p>
|
||||
<div class="section" id="ansible-1">
|
||||
<h2>ansible(1)<a class="headerlink" href="#ansible-1" title="Permalink to this headline">¶</a></h2>
|
||||
<ul class="simple">
|
||||
<li><a class="reference external" href="man/ansible.1.html">View ansible.1</a></li>
|
||||
</ul>
|
||||
</div>
|
||||
<div class="section" id="ansible-playbook-1">
|
||||
<h2>ansible-playbook(1)<a class="headerlink" href="#ansible-playbook-1" title="Permalink to this headline">¶</a></h2>
|
||||
<ul class="simple">
|
||||
<li><a class="reference external" href="man/ansible-playbook.1.html">View ansible-playbook.1</a></li>
|
||||
</ul>
|
||||
<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="examples.html"><em>Command Line Examples</em></a></dt>
|
||||
<dd>Examples of basic commands</dd>
|
||||
<dt><a class="reference internal" href="modules.html"><em>Ansible Modules</em></a></dt>
|
||||
<dd>List of built-in modules</dd>
|
||||
<dt><a class="reference internal" href="playbooks.html"><em>Playbooks</em></a></dt>
|
||||
<dd>Learning ansible’s configuration management language</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>
|
||||
© Copyright 2012 Michael DeHaan.<br/>
|
||||
Last updated on Apr 12, 2012.<br/>
|
||||
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.8.<br/>
|
||||
</p>
|
||||
</div>
|
||||
</footer>
|
||||
</body>
|
||||
</html>
|
||||
@ -0,0 +1,515 @@
|
||||
|
||||
<!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>Module Development — Ansible Documentation</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="shortcut icon" href="_static/favicon.ico"/>
|
||||
<link rel="top" title="Ansible Documentation" href="index.html" />
|
||||
<link rel="prev" title="API & Integrations" href="api.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>
|
||||
|
||||
<script type="text/javascript">
|
||||
(function() {
|
||||
var po = document.createElement('script'); po.type = 'text/javascript'; po.async = true;
|
||||
po.src = 'https://apis.google.com/js/plusone.js';
|
||||
var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(po, s);
|
||||
})();
|
||||
</script>
|
||||
|
||||
<script>(function(d, s, id) {
|
||||
var js, fjs = d.getElementsByTagName(s)[0];
|
||||
if (d.getElementById(id)) return;
|
||||
js = d.createElement(s); js.id = id;
|
||||
js.src = "//connect.facebook.net/en_US/all.js#xfbml=1";
|
||||
fjs.parentNode.insertBefore(js, fjs);
|
||||
}(document, 'script', 'facebook-jssdk'));</script>
|
||||
|
||||
</head>
|
||||
<body>
|
||||
<div class="topbar" data-scrollspy="scrollspy" >
|
||||
<div class="topbar-inner">
|
||||
<div class="container">
|
||||
<a class="brand" href="index.html">Ansible Documentation</a>
|
||||
<ul class="nav">
|
||||
|
||||
<li><a href="/">Home</A>
|
||||
<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">Getting Started</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="patterns.html">Inventory & Patterns</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="examples.html">Command Line Examples And Next Steps</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="playbooks2.html">Advanced Playbooks</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="bestpractices.html">Best Practices</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="api.html">API & Integrations</a></li>
|
||||
<li class="toctree-l1 current"><a class="current reference internal" href="">Module Development</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="#">Module Development</a><ul>
|
||||
<li><a class="reference internal" href="#tutorial">Tutorial</a></li>
|
||||
<li><a class="reference internal" href="#testing-modules">Testing Modules</a></li>
|
||||
<li><a class="reference internal" href="#reading-input">Reading Input</a></li>
|
||||
<li><a class="reference internal" href="#module-provided-facts">Module Provided ‘Facts’</a></li>
|
||||
<li><a class="reference internal" href="#common-module-boilerplate">Common Module Boilerplate</a></li>
|
||||
<li><a class="reference internal" href="#common-pitfalls">Common Pitfalls</a></li>
|
||||
<li><a class="reference internal" href="#conventions-recomendations">Conventions/Recomendations</a></li>
|
||||
<li><a class="reference internal" href="#shorthand-vs-json">Shorthand Vs JSON</a></li>
|
||||
<li><a class="reference internal" href="#sharing-your-module">Sharing Your Module</a></li>
|
||||
<li><a class="reference internal" href="#getting-your-module-into-core">Getting Your Module Into Core</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="module-development">
|
||||
<h1><a class="toc-backref" href="#contents">Module Development</a><a class="headerlink" href="#module-development" title="Permalink to this headline">¶</a></h1>
|
||||
<p>Ansible modules are reusable units of magic that can be used by the Ansible API,
|
||||
or by the <cite>ansible</cite> or <cite>ansible-playbook</cite> programs.</p>
|
||||
<p>Modules can be written in any language and are found in the path specified
|
||||
by <cite>ANSIBLE_LIBRARY_PATH</cite> or the <tt class="docutils literal"><span class="pre">--module-path</span></tt> command line option.</p>
|
||||
<div class="contents topic" id="contents">
|
||||
<p class="topic-title first">Contents</p>
|
||||
<ul class="simple">
|
||||
<li><a class="reference internal" href="#module-development" id="id2">Module Development</a><ul>
|
||||
<li><a class="reference internal" href="#tutorial" id="id3">Tutorial</a></li>
|
||||
<li><a class="reference internal" href="#testing-modules" id="id4">Testing Modules</a></li>
|
||||
<li><a class="reference internal" href="#reading-input" id="id5">Reading Input</a></li>
|
||||
<li><a class="reference internal" href="#module-provided-facts" id="id6">Module Provided ‘Facts’</a></li>
|
||||
<li><a class="reference internal" href="#common-module-boilerplate" id="id7">Common Module Boilerplate</a></li>
|
||||
<li><a class="reference internal" href="#common-pitfalls" id="id8">Common Pitfalls</a></li>
|
||||
<li><a class="reference internal" href="#conventions-recomendations" id="id9">Conventions/Recomendations</a></li>
|
||||
<li><a class="reference internal" href="#shorthand-vs-json" id="id10">Shorthand Vs JSON</a></li>
|
||||
<li><a class="reference internal" href="#sharing-your-module" id="id11">Sharing Your Module</a></li>
|
||||
<li><a class="reference internal" href="#getting-your-module-into-core" id="id12">Getting Your Module Into Core</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
</ul>
|
||||
</div>
|
||||
<div class="section" id="tutorial">
|
||||
<h2><a class="toc-backref" href="#contents">Tutorial</a><a class="headerlink" href="#tutorial" title="Permalink to this headline">¶</a></h2>
|
||||
<p>Let’s build a module to get and set the system time. For starters, let’s build
|
||||
a module that just outputs the current time.</p>
|
||||
<p>We are going to use Python here but any language is possible. Only File I/O and outputing to standard
|
||||
out are required. So, bash, C++, clojure, Python, Ruby, whatever you want
|
||||
is fine.</p>
|
||||
<p>Now Python Ansible modules contain some extremely powerful shortcuts (that all the core modules use)
|
||||
but first we are going to build a module the very hard way. The reason we do this is because modules
|
||||
written in any language OTHER than Python are going to have to do exactly this. We’ll show the easy
|
||||
way later.</p>
|
||||
<p>So, here’s an example. You would never really need to build a module to set the system time,
|
||||
the ‘command’ module could already be used to do this. Though we’re going to make one.</p>
|
||||
<p>Reading the modules that come with ansible (linked above) is a great way to learn how to write
|
||||
modules. Keep in mind, though, that some modules in ansible’s source tree are internalisms,
|
||||
so look at <cite>service</cite> or <cite>yum</cite>, and don’t stare too close into things like <cite>async_wrapper</cite> or
|
||||
you’ll turn to stone. Nobody ever executes async_wrapper directly.</p>
|
||||
<p>Ok, let’s get going with an example. We’ll use Python. For starters, save this as a file named <cite>time</cite>:</p>
|
||||
<div class="highlight-python"><div class="highlight"><pre><span class="c">#!/usr/bin/python</span>
|
||||
|
||||
<span class="kn">import</span> <span class="nn">datetime</span>
|
||||
<span class="kn">import</span> <span class="nn">json</span>
|
||||
|
||||
<span class="n">date</span> <span class="o">=</span> <span class="nb">str</span><span class="p">(</span><span class="n">datetime</span><span class="o">.</span><span class="n">datetime</span><span class="o">.</span><span class="n">now</span><span class="p">())</span>
|
||||
<span class="k">print</span> <span class="n">json</span><span class="o">.</span><span class="n">dumps</span><span class="p">({</span>
|
||||
<span class="s">"time"</span> <span class="p">:</span> <span class="n">date</span>
|
||||
<span class="p">})</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
</div>
|
||||
<div class="section" id="testing-modules">
|
||||
<h2><a class="toc-backref" href="#contents">Testing Modules</a><a class="headerlink" href="#testing-modules" title="Permalink to this headline">¶</a></h2>
|
||||
<p>There’s a useful test script in the source checkout for ansible:</p>
|
||||
<div class="highlight-python"><pre>git clone git@github.com:ansible/ansible.git
|
||||
chmod +x ansible/hacking/test-module</pre>
|
||||
</div>
|
||||
<p>Let’s run the script you just wrote with that:</p>
|
||||
<div class="highlight-python"><pre>ansible/hacking/test-module -m ./time</pre>
|
||||
</div>
|
||||
<p>You should see output that looks something like this:</p>
|
||||
<div class="highlight-python"><div class="highlight"><pre><span class="p">{</span><span class="s">u'time'</span><span class="p">:</span> <span class="s">u'2012-03-14 22:13:48.539183'</span><span class="p">}</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>If you did not, you might have a typo in your module, so recheck it and try again.</p>
|
||||
</div>
|
||||
<div class="section" id="reading-input">
|
||||
<h2><a class="toc-backref" href="#contents">Reading Input</a><a class="headerlink" href="#reading-input" title="Permalink to this headline">¶</a></h2>
|
||||
<p>Let’s modify the module to allow setting the current time. We’ll do this by seeing
|
||||
if a key value pair in the form <cite>time=<string></cite> is passed in to the module.</p>
|
||||
<p>Ansible internally saves arguments to an arguments file. So we must read the file
|
||||
and parse it. The arguments file is just a string, so any form of arguments are legal.
|
||||
Here we’ll do some basic parsing to treat the input as key=value.</p>
|
||||
<p>The example usage we are trying to achieve to set the time is:</p>
|
||||
<div class="highlight-python"><pre>time time="March 14 22:10"</pre>
|
||||
</div>
|
||||
<p>If no time parameter is set, we’ll just leave the time as is and return the current time.</p>
|
||||
<p>Let’s look at the code. Read the comments as we’ll explain as we go. Note that this
|
||||
is highly verbose because it’s intended as an educational example. You can write modules
|
||||
a lot shorter than this:</p>
|
||||
<div class="highlight-python"><div class="highlight"><pre><span class="c">#!/usr/bin/python</span>
|
||||
|
||||
<span class="c"># import some python modules that we'll use. These are all</span>
|
||||
<span class="c"># available in Python's core</span>
|
||||
|
||||
<span class="kn">import</span> <span class="nn">datetime</span>
|
||||
<span class="kn">import</span> <span class="nn">sys</span>
|
||||
<span class="kn">import</span> <span class="nn">json</span>
|
||||
<span class="kn">import</span> <span class="nn">os</span>
|
||||
<span class="kn">import</span> <span class="nn">shlex</span>
|
||||
|
||||
<span class="c"># read the argument string from the arguments file</span>
|
||||
<span class="n">args_file</span> <span class="o">=</span> <span class="n">sys</span><span class="o">.</span><span class="n">argv</span><span class="p">[</span><span class="mi">1</span><span class="p">]</span>
|
||||
<span class="n">args_data</span> <span class="o">=</span> <span class="nb">file</span><span class="p">(</span><span class="n">args_file</span><span class="p">)</span><span class="o">.</span><span class="n">read</span><span class="p">()</span>
|
||||
|
||||
<span class="c"># for this module, we're going to do key=value style arguments</span>
|
||||
<span class="c"># this is up to each module to decide what it wants, but all</span>
|
||||
<span class="c"># core modules besides 'command' and 'shell' take key=value</span>
|
||||
<span class="c"># so this is highly recommended</span>
|
||||
|
||||
<span class="n">arguments</span> <span class="o">=</span> <span class="n">shlex</span><span class="o">.</span><span class="n">split</span><span class="p">(</span><span class="n">args_data</span><span class="p">)</span>
|
||||
<span class="k">for</span> <span class="n">arg</span> <span class="ow">in</span> <span class="n">arguments</span><span class="p">:</span>
|
||||
|
||||
<span class="c"># ignore any arguments without an equals in it</span>
|
||||
<span class="k">if</span> <span class="n">arg</span><span class="o">.</span><span class="n">find</span><span class="p">(</span><span class="s">"="</span><span class="p">)</span> <span class="o">!=</span> <span class="o">-</span><span class="mi">1</span><span class="p">:</span>
|
||||
|
||||
<span class="p">(</span><span class="n">key</span><span class="p">,</span> <span class="n">value</span><span class="p">)</span> <span class="o">=</span> <span class="n">arg</span><span class="o">.</span><span class="n">split</span><span class="p">(</span><span class="s">"="</span><span class="p">)</span>
|
||||
|
||||
<span class="c"># if setting the time, the key 'time'</span>
|
||||
<span class="c"># will contain the value we want to set the time to</span>
|
||||
|
||||
<span class="k">if</span> <span class="n">key</span> <span class="o">==</span> <span class="s">"time"</span><span class="p">:</span>
|
||||
|
||||
<span class="c"># now we'll affect the change. Many modules</span>
|
||||
<span class="c"># will strive to be 'idempotent', meaning they</span>
|
||||
<span class="c"># will only make changes when the desired state</span>
|
||||
<span class="c"># expressed to the module does not match</span>
|
||||
<span class="c"># the current state. Look at 'service'</span>
|
||||
<span class="c"># or 'yum' in the main git tree for an example</span>
|
||||
<span class="c"># of how that might look.</span>
|
||||
|
||||
<span class="n">rc</span> <span class="o">=</span> <span class="n">os</span><span class="o">.</span><span class="n">system</span><span class="p">(</span><span class="s">"date -s </span><span class="se">\"</span><span class="si">%s</span><span class="se">\"</span><span class="s">"</span> <span class="o">%</span> <span class="n">value</span><span class="p">)</span>
|
||||
|
||||
<span class="c"># always handle all possible errors</span>
|
||||
<span class="c">#</span>
|
||||
<span class="c"># when returning a failure, include 'failed'</span>
|
||||
<span class="c"># in the return data, and explain the failure</span>
|
||||
<span class="c"># in 'msg'. Both of these conventions are</span>
|
||||
<span class="c"># required however additional keys and values</span>
|
||||
<span class="c"># can be added.</span>
|
||||
|
||||
<span class="k">if</span> <span class="n">rc</span> <span class="o">!=</span> <span class="mi">0</span><span class="p">:</span>
|
||||
<span class="k">print</span> <span class="n">json</span><span class="o">.</span><span class="n">dumps</span><span class="p">({</span>
|
||||
<span class="s">"failed"</span> <span class="p">:</span> <span class="bp">True</span><span class="p">,</span>
|
||||
<span class="s">"msg"</span> <span class="p">:</span> <span class="s">"failed setting the time"</span>
|
||||
<span class="p">})</span>
|
||||
<span class="n">sys</span><span class="o">.</span><span class="n">exit</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span>
|
||||
|
||||
<span class="c"># when things do not fail, we do not</span>
|
||||
<span class="c"># have any restrictions on what kinds of</span>
|
||||
<span class="c"># data are returned, but it's always a</span>
|
||||
<span class="c"># good idea to include whether or not</span>
|
||||
<span class="c"># a change was made, as that will allow</span>
|
||||
<span class="c"># notifiers to be used in playbooks.</span>
|
||||
|
||||
<span class="n">date</span> <span class="o">=</span> <span class="nb">str</span><span class="p">(</span><span class="n">datetime</span><span class="o">.</span><span class="n">datetime</span><span class="o">.</span><span class="n">now</span><span class="p">())</span>
|
||||
<span class="k">print</span> <span class="n">json</span><span class="o">.</span><span class="n">dumps</span><span class="p">({</span>
|
||||
<span class="s">"time"</span> <span class="p">:</span> <span class="n">date</span><span class="p">,</span>
|
||||
<span class="s">"changed"</span> <span class="p">:</span> <span class="bp">True</span>
|
||||
<span class="p">})</span>
|
||||
<span class="n">sys</span><span class="o">.</span><span class="n">exit</span><span class="p">(</span><span class="mi">0</span><span class="p">)</span>
|
||||
|
||||
<span class="c"># if no parameters are sent, the module may or</span>
|
||||
<span class="c"># may not error out, this one will just</span>
|
||||
<span class="c"># return the time</span>
|
||||
|
||||
<span class="n">date</span> <span class="o">=</span> <span class="nb">str</span><span class="p">(</span><span class="n">datetime</span><span class="o">.</span><span class="n">datetime</span><span class="o">.</span><span class="n">now</span><span class="p">())</span>
|
||||
<span class="k">print</span> <span class="n">json</span><span class="o">.</span><span class="n">dumps</span><span class="p">({</span>
|
||||
<span class="s">"time"</span> <span class="p">:</span> <span class="n">date</span>
|
||||
<span class="p">})</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>Let’s test that module:</p>
|
||||
<div class="highlight-python"><pre>ansible/hacking/test-module -m ./time -a time=\"March 14 12:23\"</pre>
|
||||
</div>
|
||||
<p>This should return something like:</p>
|
||||
<div class="highlight-python"><div class="highlight"><pre><span class="p">{</span><span class="s">"changed"</span><span class="p">:</span> <span class="bp">True</span><span class="p">,</span> <span class="s">"time"</span><span class="p">:</span> <span class="s">"2012-03-14 12:23:00.000307"</span><span class="p">}</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
</div>
|
||||
<div class="section" id="module-provided-facts">
|
||||
<h2><a class="toc-backref" href="#contents">Module Provided ‘Facts’</a><a class="headerlink" href="#module-provided-facts" title="Permalink to this headline">¶</a></h2>
|
||||
<p>The ‘setup’ module that ships with Ansible provides many variables about a system that can be used in playbooks
|
||||
and templates. However, it’s possible to also add your own facts without modifying the system module. To do
|
||||
this, just have the module return a <cite>ansible_facts</cite> key, like so, along with other return data:</p>
|
||||
<div class="highlight-python"><pre>{
|
||||
"changed" : True,
|
||||
"rc" : 5,
|
||||
"ansible_facts" : {
|
||||
"leptons" : 5000
|
||||
"colors" : {
|
||||
"red" : "FF0000",
|
||||
"white" : "FFFFFF"
|
||||
}
|
||||
}
|
||||
}</pre>
|
||||
</div>
|
||||
<p>These ‘facts’ will be available to all statements called after that module (but not before) in the playbook.
|
||||
A good idea might be make a module called ‘site_facts’ and always call it at the top of each playbook, though
|
||||
we’re always open to improving the selection of core facts in Ansible as well.</p>
|
||||
</div>
|
||||
<div class="section" id="common-module-boilerplate">
|
||||
<h2><a class="toc-backref" href="#contents">Common Module Boilerplate</a><a class="headerlink" href="#common-module-boilerplate" title="Permalink to this headline">¶</a></h2>
|
||||
<p>As mentioned, if you are writing a module in Python, there are some very powerful shortcuts you can use.
|
||||
Modules are still transferred as one file, but an arguments file is no longer needed, so these are not
|
||||
only shorter in terms of code, they are actually FASTER in terms of execution time.</p>
|
||||
<p>Rather than mention these here, the best way to learn is to read some of the <a class="reference external" href="https://github.com/ansible/ansible/tree/devel/library">source of the modules</a> that come with Ansible.</p>
|
||||
<p>The ‘group’ and ‘user’ modules are reasonably non-trival and showcase what this looks like.</p>
|
||||
<p>Key parts include always ending the module file with:</p>
|
||||
<div class="highlight-python"><div class="highlight"><pre><span class="c"># include magic from lib/ansible/module_common.py</span>
|
||||
<span class="c">#<<INCLUDE_ANSIBLE_MODULE_COMMON>></span>
|
||||
<span class="n">main</span><span class="p">()</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>And instantiating the module class like:</p>
|
||||
<div class="highlight-python"><div class="highlight"><pre><span class="n">module</span> <span class="o">=</span> <span class="n">AnsibleModule</span><span class="p">(</span>
|
||||
<span class="n">argument_spec</span> <span class="o">=</span> <span class="nb">dict</span><span class="p">(</span>
|
||||
<span class="n">state</span> <span class="o">=</span> <span class="nb">dict</span><span class="p">(</span><span class="n">default</span><span class="o">=</span><span class="s">'present'</span><span class="p">,</span> <span class="n">choices</span><span class="o">=</span><span class="p">[</span><span class="s">'present'</span><span class="p">,</span> <span class="s">'absent'</span><span class="p">]),</span>
|
||||
<span class="n">name</span> <span class="o">=</span> <span class="nb">dict</span><span class="p">(</span><span class="n">required</span><span class="o">=</span><span class="bp">True</span><span class="p">),</span>
|
||||
<span class="n">enabled</span> <span class="o">=</span> <span class="nb">dict</span><span class="p">(</span><span class="n">required</span><span class="o">=</span><span class="bp">True</span><span class="p">,</span> <span class="n">choices</span><span class="o">=</span><span class="n">BOOLEANS</span><span class="p">),</span>
|
||||
<span class="n">something</span> <span class="o">=</span> <span class="nb">dict</span><span class="p">(</span><span class="n">aliases</span><span class="o">=</span><span class="p">[</span><span class="s">'whatever'</span><span class="p">])</span>
|
||||
<span class="p">)</span>
|
||||
<span class="p">)</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>The AnsibleModule provides lots of common code for handling returns, parses your arguments
|
||||
for you, and allows you to check inputs.</p>
|
||||
<p>Successful returns are made like this:</p>
|
||||
<div class="highlight-python"><div class="highlight"><pre><span class="n">module</span><span class="o">.</span><span class="n">exit_json</span><span class="p">(</span><span class="n">changed</span><span class="o">=</span><span class="bp">True</span><span class="p">,</span> <span class="n">something_else</span><span class="o">=</span><span class="mi">12345</span><span class="p">)</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>And failures are just as simple (where ‘msg’ is a required parameter to explain the error):</p>
|
||||
<div class="highlight-python"><div class="highlight"><pre><span class="n">module</span><span class="o">.</span><span class="n">fail_json</span><span class="p">(</span><span class="n">msg</span><span class="o">=</span><span class="s">"Something fatal happened"</span><span class="p">)</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>There are also other useful functions in the module class, such as module.md5(path). See
|
||||
lib/ansible/module_common.py in the source checkout for implementation details.</p>
|
||||
<p>Again, modules developed this way are best tested with the hacking/test-module script in the git
|
||||
source checkout. Because of the magic involved, this is really the only way the scripts
|
||||
can function outside of Ansible.</p>
|
||||
<p>If submitting a module to ansible’s core code, which we encourage, use of the AnsibleModule
|
||||
class is required.</p>
|
||||
</div>
|
||||
<div class="section" id="common-pitfalls">
|
||||
<h2><a class="toc-backref" href="#contents">Common Pitfalls</a><a class="headerlink" href="#common-pitfalls" title="Permalink to this headline">¶</a></h2>
|
||||
<p>You should also never do this in a module:</p>
|
||||
<div class="highlight-python"><div class="highlight"><pre><span class="k">print</span> <span class="s">"some status message"</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>Because the output is supposed to be valid JSON. Except that’s not quite true,
|
||||
but we’ll get to that later.</p>
|
||||
<p>Modules must not output anything on standard error, because the system will merge
|
||||
standard out with standard error and prevent the JSON from parsing. Capturing standard
|
||||
error and returning it as a variable in the JSON on standard out is fine, and is, in fact,
|
||||
how the command module is implemented.</p>
|
||||
<p>If a module returns stderr or otherwise fails to produce valid JSON, the actual output
|
||||
will still be shown in Ansible, but the command will not succeed.</p>
|
||||
<p>Always use the hacking/test-module script when developing modules and it will warn
|
||||
you about these kind of things.</p>
|
||||
</div>
|
||||
<div class="section" id="conventions-recomendations">
|
||||
<h2><a class="toc-backref" href="#contents">Conventions/Recomendations</a><a class="headerlink" href="#conventions-recomendations" title="Permalink to this headline">¶</a></h2>
|
||||
<p>As a reminder from the example code above, here are some basic conventions
|
||||
and guidelines:</p>
|
||||
<ul class="simple">
|
||||
<li>If the module is addressing an object, the parameter for that object should be called ‘name’ whenever possible, or accept ‘name’ as an alias.</li>
|
||||
<li>If you have a company module that returns facts specific to your installations, a good name for this module is <cite>site_facts</cite>.</li>
|
||||
<li>Modules accepting boolean status should generally accept ‘yes’, ‘no’, ‘true’, ‘false’, or anything else a user may likely throw at them. The AnsibleModule common code supports this with “choices=BOOLEANS” and a module.boolean(value) casting function.</li>
|
||||
<li>Include a minimum of dependencies if possible. If there are dependencies, document them at the top of the module file, and have the module raise JSON error messages when the import fails.</li>
|
||||
<li>Modules must be self contained in one file to be auto-transferred by ansible.</li>
|
||||
<li>If packaging modules in an RPM, they only need to be installed on the control machine and should be dropped into /usr/share/ansible. This is entirely optional and up to you.</li>
|
||||
<li>Modules should return JSON or key=value results all on one line. JSON is best if you can do JSON. All return types must be hashes (dictionaries) although they can be nested. Lists or simple scalar values are not supported, though they can be trivially contained inside a dictionary.</li>
|
||||
<li>In the event of failure, a key of ‘failed’ should be included, along with a string explanation in ‘msg’. Modules that raise tracebacks (stacktraces) are generally considered ‘poor’ modules, though Ansible can deal with these returns and will automatically convert anything unparseable into a failed result. If you are using the AnsibleModule common Python code, the ‘failed’ element will be included for you automatically when you call ‘fail_json’.</li>
|
||||
<li>Return codes from modules are not actually not signficant, but continue on with 0=success and non-zero=failure for reasons of future proofing.</li>
|
||||
<li>As results from many hosts will be aggregrated at once, modules should return only relevant output. Returning the entire contents of a log file is generally bad form.</li>
|
||||
</ul>
|
||||
</div>
|
||||
<div class="section" id="shorthand-vs-json">
|
||||
<h2><a class="toc-backref" href="#contents">Shorthand Vs JSON</a><a class="headerlink" href="#shorthand-vs-json" title="Permalink to this headline">¶</a></h2>
|
||||
<p>To make it easier to write modules in bash and in cases where a JSON
|
||||
module might not be available, it is acceptable for a module to return
|
||||
key=value output all on one line, like this. The Ansible parser
|
||||
will know what to do:</p>
|
||||
<div class="highlight-python"><pre>somekey=1 somevalue=2 rc=3 favcolor=red</pre>
|
||||
</div>
|
||||
<p>If you’re writing a module in Python or Ruby or whatever, though, returning
|
||||
JSON is probably the simplest way to go.</p>
|
||||
</div>
|
||||
<div class="section" id="sharing-your-module">
|
||||
<h2><a class="toc-backref" href="#contents">Sharing Your Module</a><a class="headerlink" href="#sharing-your-module" title="Permalink to this headline">¶</a></h2>
|
||||
<p>If you think your module is generally useful to others, a good place to share it
|
||||
is in <a class="reference external" href="https://github.com/ansible/ansible-resources">Ansible Resources</a>. This is maintained
|
||||
as a simple repo with pointers to other github projects.</p>
|
||||
<p>Contrib modules here can be implemented in a variety of languages.
|
||||
We would like to build up as many of these as possible in as many languages as possible.</p>
|
||||
<p><a class="reference external" href="http://groups.google.com/group/ansible-project">Ansible Mailing List</a></p>
|
||||
</div>
|
||||
<div class="section" id="getting-your-module-into-core">
|
||||
<h2><a class="toc-backref" href="#contents">Getting Your Module Into Core</a><a class="headerlink" href="#getting-your-module-into-core" title="Permalink to this headline">¶</a></h2>
|
||||
<p>High-quality modules with minimal dependencies
|
||||
can be included in the core, but core modules (just due to the programming
|
||||
preferences of the developers) will need to be implemented in Python and use
|
||||
the AnsibleModule common code, and should generally use consistent arguments with the rest of
|
||||
the program. Stop by the mailing list to inquire about requirements.</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>Learn about available modules</dd>
|
||||
<dt><a class="reference external" href="https://github.com/ansible/ansible-resources">Ansible Resources</a></dt>
|
||||
<dd>User contributed playbooks, modules, and articles</dd>
|
||||
<dt><a class="reference external" href="https://github.com/ansible/ansible/tree/devel/library">Github modules directory</a></dt>
|
||||
<dd>Browse source of core modules</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>
|
||||
|
||||
|
||||
<br/>
|
||||
</div>
|
||||
<footer class="footer">
|
||||
<div class="container">
|
||||
<p>
|
||||
<p>
|
||||
© Copyright 2012 Michael DeHaan.<br/>
|
||||
Last updated on Oct 08, 2012.<br/>
|
||||
</p>
|
||||
</div>
|
||||
</footer>
|
||||
</body>
|
||||
</html>
|
||||
File diff suppressed because it is too large
Load Diff
Binary file not shown.
|
After Width: | Height: | Size: 54 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 90 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 52 KiB |
@ -0,0 +1,394 @@
|
||||
|
||||
<!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>Inventory & Patterns — Ansible Documentation</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="shortcut icon" href="_static/favicon.ico"/>
|
||||
<link rel="top" title="Ansible Documentation" href="index.html" />
|
||||
<link rel="next" title="Command Line Examples And Next Steps" href="examples.html" />
|
||||
<link rel="prev" title="Getting Started" href="gettingstarted.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>
|
||||
|
||||
<script type="text/javascript">
|
||||
(function() {
|
||||
var po = document.createElement('script'); po.type = 'text/javascript'; po.async = true;
|
||||
po.src = 'https://apis.google.com/js/plusone.js';
|
||||
var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(po, s);
|
||||
})();
|
||||
</script>
|
||||
|
||||
<script>(function(d, s, id) {
|
||||
var js, fjs = d.getElementsByTagName(s)[0];
|
||||
if (d.getElementById(id)) return;
|
||||
js = d.createElement(s); js.id = id;
|
||||
js.src = "//connect.facebook.net/en_US/all.js#xfbml=1";
|
||||
fjs.parentNode.insertBefore(js, fjs);
|
||||
}(document, 'script', 'facebook-jssdk'));</script>
|
||||
|
||||
</head>
|
||||
<body>
|
||||
<div class="topbar" data-scrollspy="scrollspy" >
|
||||
<div class="topbar-inner">
|
||||
<div class="container">
|
||||
<a class="brand" href="index.html">Ansible Documentation</a>
|
||||
<ul class="nav">
|
||||
|
||||
<li><a href="/">Home</A>
|
||||
<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">Getting Started</a></li>
|
||||
<li class="toctree-l1 current"><a class="current reference internal" href="">Inventory & Patterns</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="examples.html">Command Line Examples And Next Steps</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="playbooks2.html">Advanced Playbooks</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="bestpractices.html">Best Practices</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="api.html">API & Integrations</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="moduledev.html">Module Development</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="#">Inventory & Patterns</a><ul>
|
||||
<li><a class="reference internal" href="#hosts-and-groups">Hosts and Groups</a></li>
|
||||
<li><a class="reference internal" href="#selecting-targets">Selecting Targets</a></li>
|
||||
<li><a class="reference internal" href="#host-variables">Host Variables</a></li>
|
||||
<li><a class="reference internal" href="#group-variables">Group Variables</a></li>
|
||||
<li><a class="reference internal" href="#groups-of-groups-and-group-variables">Groups of Groups, and Group Variables</a></li>
|
||||
<li><a class="reference internal" href="#splitting-out-host-and-group-specific-data">Splitting Out Host and Group Specific Data</a></li>
|
||||
<li><a class="reference internal" href="#yaml-inventory">YAML Inventory</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="inventory-patterns">
|
||||
<span id="patterns"></span><h1><a class="toc-backref" href="#table-of-contents">Inventory & Patterns</a><a class="headerlink" href="#inventory-patterns" title="Permalink to this headline">¶</a></h1>
|
||||
<p>Ansible works against multiple systems in your infrastructure at the
|
||||
same time. It does this by selecting portions of systems listed in
|
||||
Ansible’s inventory file, which defaults to /etc/ansible/hosts.</p>
|
||||
<div class="contents topic" id="table-of-contents">
|
||||
<p class="topic-title first"><cite>Table of contents</cite></p>
|
||||
<ul class="simple">
|
||||
<li><a class="reference internal" href="#inventory-patterns" id="id1">Inventory & Patterns</a><ul>
|
||||
<li><a class="reference internal" href="#hosts-and-groups" id="id2">Hosts and Groups</a></li>
|
||||
<li><a class="reference internal" href="#selecting-targets" id="id3">Selecting Targets</a></li>
|
||||
<li><a class="reference internal" href="#host-variables" id="id4">Host Variables</a></li>
|
||||
<li><a class="reference internal" href="#group-variables" id="id5">Group Variables</a></li>
|
||||
<li><a class="reference internal" href="#groups-of-groups-and-group-variables" id="id6">Groups of Groups, and Group Variables</a></li>
|
||||
<li><a class="reference internal" href="#splitting-out-host-and-group-specific-data" id="id7">Splitting Out Host and Group Specific Data</a></li>
|
||||
<li><a class="reference internal" href="#yaml-inventory" id="id8">YAML Inventory</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
</ul>
|
||||
</div>
|
||||
<div class="section" id="hosts-and-groups">
|
||||
<span id="inventoryformat"></span><h2><a class="toc-backref" href="#table-of-contents">Hosts and Groups</a><a class="headerlink" href="#hosts-and-groups" title="Permalink to this headline">¶</a></h2>
|
||||
<p>The format for /etc/ansible/hosts is an INI format and looks like this:</p>
|
||||
<div class="highlight-python"><div class="highlight"><pre><span class="n">mail</span><span class="o">.</span><span class="n">example</span><span class="o">.</span><span class="n">com</span>
|
||||
|
||||
<span class="p">[</span><span class="n">webservers</span><span class="p">]</span>
|
||||
<span class="n">foo</span><span class="o">.</span><span class="n">example</span><span class="o">.</span><span class="n">com</span>
|
||||
<span class="n">bar</span><span class="o">.</span><span class="n">example</span><span class="o">.</span><span class="n">com</span>
|
||||
|
||||
<span class="p">[</span><span class="n">dbservers</span><span class="p">]</span>
|
||||
<span class="n">one</span><span class="o">.</span><span class="n">example</span><span class="o">.</span><span class="n">com</span>
|
||||
<span class="n">two</span><span class="o">.</span><span class="n">example</span><span class="o">.</span><span class="n">com</span>
|
||||
<span class="n">three</span><span class="o">.</span><span class="n">example</span><span class="o">.</span><span class="n">com</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>The things in brackets are group names. You don’t have to have them,
|
||||
but they are useful.</p>
|
||||
<p>If you have hosts that run on non-standard SSH ports you can put the port number
|
||||
after the hostname with a colon.</p>
|
||||
<blockquote>
|
||||
<div>four.example.com:5309</div></blockquote>
|
||||
<p>In 0.6 and later, if you have a lot of hosts following similar patterns you can do this rather than listing each hostname:</p>
|
||||
<div class="highlight-python"><div class="highlight"><pre><span class="p">[</span><span class="n">webservers</span><span class="p">]</span>
|
||||
<span class="n">www</span><span class="p">[</span><span class="mo">01</span><span class="p">:</span><span class="mi">50</span><span class="p">]</span><span class="o">.</span><span class="n">example</span><span class="o">.</span><span class="n">com</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>Leading zeros can be included or removed, as desired, and the ranges are inclusive.</p>
|
||||
</div>
|
||||
<div class="section" id="selecting-targets">
|
||||
<h2><a class="toc-backref" href="#table-of-contents">Selecting Targets</a><a class="headerlink" href="#selecting-targets" title="Permalink to this headline">¶</a></h2>
|
||||
<p>We’ll go over how to use the command line in <a class="reference internal" href="examples.html"><em>Command Line Examples And Next Steps</em></a> section, however, basically it looks like this:</p>
|
||||
<div class="highlight-python"><pre>ansible <pattern_goes_here> -m <module_name> -a <arguments></pre>
|
||||
</div>
|
||||
<p>Such as:</p>
|
||||
<div class="highlight-python"><pre>ansible webservers -m service -a "name=httpd state=restarted"</pre>
|
||||
</div>
|
||||
<p>Within <a class="reference internal" href="playbooks.html"><em>Playbooks</em></a>, these patterns can be used for even greater purposes.</p>
|
||||
<p>Anyway, to use Ansible, you’ll first need to know how to tell Ansible which hosts in your inventory file to talk to.
|
||||
This is done by designating particular host names or groups of hosts.</p>
|
||||
<p>The following patterns target all hosts in the inventory file:</p>
|
||||
<div class="highlight-python"><pre>all
|
||||
*</pre>
|
||||
</div>
|
||||
<p>Basically ‘all’ is an alias for ‘*’. It is also possible to address a specific host or hosts:</p>
|
||||
<div class="highlight-python"><pre>one.example.com
|
||||
one.example.com:two.example.com
|
||||
192.168.1.50
|
||||
192.168.1.*</pre>
|
||||
</div>
|
||||
<p>The following patterns address one or more groups, which are denoted
|
||||
with the aforementioned bracket headers in the inventory file:</p>
|
||||
<div class="highlight-python"><pre>webservers
|
||||
webservers:dbservers</pre>
|
||||
</div>
|
||||
<p>You can exclude groups as well, for instance, all webservers not in Phoenix:</p>
|
||||
<div class="highlight-python"><pre>webservers:!phoenix</pre>
|
||||
</div>
|
||||
<p>Individual host names (or IPs), but not groups, can also be referenced using
|
||||
wildcards:</p>
|
||||
<div class="highlight-python"><pre>*.example.com
|
||||
*.com</pre>
|
||||
</div>
|
||||
<p>It’s also ok to mix wildcard patterns and groups at the same time:</p>
|
||||
<div class="highlight-python"><pre>one*.com:dbservers</pre>
|
||||
</div>
|
||||
<p>Easy enough. See <a class="reference internal" href="examples.html"><em>Command Line Examples And Next Steps</em></a> and then <a class="reference internal" href="playbooks.html"><em>Playbooks</em></a> for how to do things to selected hosts.</p>
|
||||
</div>
|
||||
<div class="section" id="host-variables">
|
||||
<h2><a class="toc-backref" href="#table-of-contents">Host Variables</a><a class="headerlink" href="#host-variables" title="Permalink to this headline">¶</a></h2>
|
||||
<p>It is easy to assign variables to hosts that will be used later in playbooks:</p>
|
||||
<div class="highlight-python"><pre>[atlanta]
|
||||
host1 http_port=80 maxRequestsPerChild=808
|
||||
host2 http_port=303 maxRequestsPerChild=909</pre>
|
||||
</div>
|
||||
</div>
|
||||
<div class="section" id="group-variables">
|
||||
<h2><a class="toc-backref" href="#table-of-contents">Group Variables</a><a class="headerlink" href="#group-variables" title="Permalink to this headline">¶</a></h2>
|
||||
<p>Variables can also be applied to an entire group at once:</p>
|
||||
<div class="highlight-python"><pre>[atlanta]
|
||||
host1
|
||||
host2
|
||||
|
||||
[atlanta:vars]
|
||||
ntp_server=ntp.atlanta.example.com
|
||||
proxy=proxy.atlanta.example.com</pre>
|
||||
</div>
|
||||
</div>
|
||||
<div class="section" id="groups-of-groups-and-group-variables">
|
||||
<h2><a class="toc-backref" href="#table-of-contents">Groups of Groups, and Group Variables</a><a class="headerlink" href="#groups-of-groups-and-group-variables" title="Permalink to this headline">¶</a></h2>
|
||||
<p>It is also possible to make groups of groups and assign
|
||||
variables to groups. These variables can be used by /usr/bin/ansible-playbook, but not
|
||||
/usr/bin/ansible:</p>
|
||||
<div class="highlight-python"><pre>[atlanta]
|
||||
host1
|
||||
host2
|
||||
|
||||
[raleigh]
|
||||
host2
|
||||
host3
|
||||
|
||||
[southeast:children]
|
||||
atlanta
|
||||
raleigh
|
||||
|
||||
[southeast:vars]
|
||||
some_server=foo.southeast.example.com
|
||||
halon_system_timeout=30
|
||||
self_destruct_countdown=60
|
||||
escape_pods=2
|
||||
|
||||
[usa:children]
|
||||
southeast
|
||||
northeast
|
||||
southwest
|
||||
southeast</pre>
|
||||
</div>
|
||||
<p>If you need to store lists or hash data, or prefer to keep host and group specific variables
|
||||
seperate from the inventory file, see the next section.</p>
|
||||
</div>
|
||||
<div class="section" id="splitting-out-host-and-group-specific-data">
|
||||
<h2><a class="toc-backref" href="#table-of-contents">Splitting Out Host and Group Specific Data</a><a class="headerlink" href="#splitting-out-host-and-group-specific-data" title="Permalink to this headline">¶</a></h2>
|
||||
<p class="versionadded">
|
||||
<span class="versionmodified">New in version 0.6.</span></p>
|
||||
<p>In addition to the storing variables directly in the INI file, host
|
||||
and group variables can be stored in individual files relative to the
|
||||
inventory file. These variable files are in YAML format.</p>
|
||||
<p>Assuming the inventory file path is:</p>
|
||||
<div class="highlight-python"><pre>/etc/ansible/hosts</pre>
|
||||
</div>
|
||||
<p>If the host is named ‘foosball’, and in groups ‘raleigh’ and ‘webservers’, variables
|
||||
in YAML files at the following locations will be made available to the host:</p>
|
||||
<div class="highlight-python"><pre>/etc/ansible/group_vars/raleigh
|
||||
/etc/ansible/group_vars/webservers
|
||||
/etc/ansible/host_vars/foosball</pre>
|
||||
</div>
|
||||
<p>For instance, suppose you have hosts grouped by datacenter, and each datacenter
|
||||
uses some different servers. The data in the groupfile ‘/etc/ansible/group_vars/raleigh’ for
|
||||
the ‘raleigh’ group might look like:</p>
|
||||
<div class="highlight-python"><pre>---
|
||||
ntp_server: acme.example.org
|
||||
database_server: storage.example.org</pre>
|
||||
</div>
|
||||
<p>It is ok if these files do not exist, this is an optional feature.</p>
|
||||
<p>Tip: Keeping your inventory file and variables in a git repo (or other version control)
|
||||
is an excellent way to track changes to your inventory and host variables.</p>
|
||||
<p class="versionadded">
|
||||
<span class="versionmodified">New in version 0.5: </span>If you ever have two python interpreters on a system, set a
|
||||
variable called ‘ansible_python_interpreter’ to the Python
|
||||
interpreter path you would like to use.</p>
|
||||
</div>
|
||||
<div class="section" id="yaml-inventory">
|
||||
<h2><a class="toc-backref" href="#table-of-contents">YAML Inventory</a><a class="headerlink" href="#yaml-inventory" title="Permalink to this headline">¶</a></h2>
|
||||
<p class="deprecated">
|
||||
<span class="versionmodified">Deprecated since version 0.7.</span></p>
|
||||
<p>Ansible’s YAML inventory format is deprecated and will be removed in
|
||||
Ansible 0.7. Ansible 0.6 includes a <a class="reference external" href="https://github.com/ansible/ansible/blob/devel/examples/scripts/yaml_to_ini.py">conversion script</a>.</p>
|
||||
<p>Usage:</p>
|
||||
<div class="highlight-python"><div class="highlight"><pre><span class="n">yaml_to_ini</span><span class="o">.</span><span class="n">py</span> <span class="o">/</span><span class="n">etc</span><span class="o">/</span><span class="n">ansible</span><span class="o">/</span><span class="n">hosts</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<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="examples.html"><em>Command Line Examples And Next Steps</em></a></dt>
|
||||
<dd>Examples of basic commands</dd>
|
||||
<dt><a class="reference internal" href="playbooks.html"><em>Playbooks</em></a></dt>
|
||||
<dd>Learning ansible’s configuration management language</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>
|
||||
|
||||
|
||||
<br/>
|
||||
</div>
|
||||
<footer class="footer">
|
||||
<div class="container">
|
||||
<p>
|
||||
<p>
|
||||
© Copyright 2012 Michael DeHaan.<br/>
|
||||
Last updated on Oct 08, 2012.<br/>
|
||||
</p>
|
||||
</div>
|
||||
</footer>
|
||||
</body>
|
||||
</html>
|
||||
@ -0,0 +1,567 @@
|
||||
|
||||
<!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>Playbooks — Ansible Documentation</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="shortcut icon" href="_static/favicon.ico"/>
|
||||
<link rel="top" title="Ansible Documentation" href="index.html" />
|
||||
<link rel="next" title="Advanced Playbooks" href="playbooks2.html" />
|
||||
<link rel="prev" title="YAML Syntax" href="YAMLSyntax.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>
|
||||
|
||||
<script type="text/javascript">
|
||||
(function() {
|
||||
var po = document.createElement('script'); po.type = 'text/javascript'; po.async = true;
|
||||
po.src = 'https://apis.google.com/js/plusone.js';
|
||||
var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(po, s);
|
||||
})();
|
||||
</script>
|
||||
|
||||
<script>(function(d, s, id) {
|
||||
var js, fjs = d.getElementsByTagName(s)[0];
|
||||
if (d.getElementById(id)) return;
|
||||
js = d.createElement(s); js.id = id;
|
||||
js.src = "//connect.facebook.net/en_US/all.js#xfbml=1";
|
||||
fjs.parentNode.insertBefore(js, fjs);
|
||||
}(document, 'script', 'facebook-jssdk'));</script>
|
||||
|
||||
</head>
|
||||
<body>
|
||||
<div class="topbar" data-scrollspy="scrollspy" >
|
||||
<div class="topbar-inner">
|
||||
<div class="container">
|
||||
<a class="brand" href="index.html">Ansible Documentation</a>
|
||||
<ul class="nav">
|
||||
|
||||
<li><a href="/">Home</A>
|
||||
<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">Getting Started</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="patterns.html">Inventory & Patterns</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="examples.html">Command Line Examples And Next Steps</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 current"><a class="current reference internal" href="">Playbooks</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="playbooks2.html">Advanced Playbooks</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="bestpractices.html">Best Practices</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="api.html">API & Integrations</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="moduledev.html">Module Development</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="#">Playbooks</a><ul>
|
||||
<li><a class="reference internal" href="#introduction">Introduction</a></li>
|
||||
<li><a class="reference internal" href="#playbook-language-example">Playbook Language Example</a></li>
|
||||
<li><a class="reference internal" href="#basics">Basics</a><ul>
|
||||
<li><a class="reference internal" href="#hosts-and-users">Hosts and Users</a></li>
|
||||
<li><a class="reference internal" href="#vars-section">Vars section</a></li>
|
||||
<li><a class="reference internal" href="#tasks-list">Tasks list</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><a class="reference internal" href="#running-operations-on-change">Running Operations On Change</a></li>
|
||||
<li><a class="reference internal" href="#include-files-and-encouraging-reuse">Include Files And Encouraging Reuse</a></li>
|
||||
<li><a class="reference internal" href="#executing-a-playbook">Executing A Playbook</a></li>
|
||||
<li><a class="reference internal" href="#tips-and-tricks">Tips and Tricks</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="playbooks">
|
||||
<h1><a class="toc-backref" href="#contents">Playbooks</a><a class="headerlink" href="#playbooks" title="Permalink to this headline">¶</a></h1>
|
||||
<div class="contents topic" id="contents">
|
||||
<p class="topic-title first">Contents</p>
|
||||
<ul class="simple">
|
||||
<li><a class="reference internal" href="#playbooks" id="id2">Playbooks</a><ul>
|
||||
<li><a class="reference internal" href="#introduction" id="id3">Introduction</a></li>
|
||||
<li><a class="reference internal" href="#playbook-language-example" id="id4">Playbook Language Example</a></li>
|
||||
<li><a class="reference internal" href="#basics" id="id5">Basics</a></li>
|
||||
<li><a class="reference internal" href="#running-operations-on-change" id="id6">Running Operations On Change</a></li>
|
||||
<li><a class="reference internal" href="#include-files-and-encouraging-reuse" id="id7">Include Files And Encouraging Reuse</a></li>
|
||||
<li><a class="reference internal" href="#executing-a-playbook" id="id8">Executing A Playbook</a></li>
|
||||
<li><a class="reference internal" href="#tips-and-tricks" id="id9">Tips and Tricks</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
</ul>
|
||||
</div>
|
||||
<div class="section" id="introduction">
|
||||
<h2><a class="toc-backref" href="#contents">Introduction</a><a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
|
||||
<p>Playbooks are a completely different way to use ansible than in task execution mode, and are
|
||||
particularly powerful. Simply put, playbooks are the basis for a really simple
|
||||
configuration management and multi-machine deployment system,
|
||||
unlike any that already exist, and one that is very well suited to deploying complex applications.</p>
|
||||
<p>Playbooks can declare configurations, but they can also orchestrate steps of
|
||||
any manual ordered process, even as different steps must bounce back and forth
|
||||
between sets of machines in particular orders. They can launch tasks
|
||||
synchronously or asynchronously.</p>
|
||||
<p>While you might run the main /usr/bin/ansible program for ad-hoc
|
||||
tasks, playbooks are more likely to be kept in source control and used
|
||||
to push out your configuration or assure the configurations of your
|
||||
remote systems are in spec.</p>
|
||||
<p>Let’s dive in and see how they work. As you go, you may wish to open
|
||||
the <a class="reference external" href="https://github.com/ansible/ansible/tree/devel/examples/playbooks">github examples directory</a> in
|
||||
another tab, so you can apply the theory to what things look like in practice.</p>
|
||||
</div>
|
||||
<div class="section" id="playbook-language-example">
|
||||
<h2><a class="toc-backref" href="#contents">Playbook Language Example</a><a class="headerlink" href="#playbook-language-example" title="Permalink to this headline">¶</a></h2>
|
||||
<p>Playbooks are expressed in YAML format and have a minimum of syntax.
|
||||
Each playbook is composed of one or more ‘plays’ in a list.</p>
|
||||
<p>The goal of a play is map a group of hosts to some well defined roles, represented by
|
||||
things ansible called tasks. At the basic level, a task is nothing more than a call
|
||||
to an ansible module, which you should have learned about in earlier chapters.</p>
|
||||
<p>By composing a playbook of multiple ‘plays’, it is possible to
|
||||
orchestrate multi-machine deployments, running certain steps on all
|
||||
machines in the webservers group, then certain steps on the database
|
||||
server group, then more commands back on the webservers group, etc.</p>
|
||||
<p>For starters, here’s a playbook that contains just one play:</p>
|
||||
<div class="highlight-python"><pre>---
|
||||
- hosts: webservers
|
||||
vars:
|
||||
http_port: 80
|
||||
max_clients: 200
|
||||
user: root
|
||||
tasks:
|
||||
- name: ensure apache is at the latest version
|
||||
action: yum pkg=httpd state=latest
|
||||
- name: write the apache config file
|
||||
action: template src=/srv/httpd.j2 dest=/etc/httpd.conf
|
||||
notify:
|
||||
- restart apache
|
||||
- name: ensure apache is running
|
||||
action: service name=httpd state=started
|
||||
handlers:
|
||||
- name: restart apache
|
||||
action: service name=httpd state=restarted</pre>
|
||||
</div>
|
||||
<p>Below, we’ll break down what the various features of the playbook language are.</p>
|
||||
</div>
|
||||
<div class="section" id="basics">
|
||||
<h2><a class="toc-backref" href="#contents">Basics</a><a class="headerlink" href="#basics" title="Permalink to this headline">¶</a></h2>
|
||||
<div class="section" id="hosts-and-users">
|
||||
<h3>Hosts and Users<a class="headerlink" href="#hosts-and-users" title="Permalink to this headline">¶</a></h3>
|
||||
<p>For each play in a playbook, you get to choose which machines in your infrastructure
|
||||
to target and what remote user to complete the steps (called tasks) as.</p>
|
||||
<p>The <cite>hosts</cite> line is a list of one or more groups or host patterns,
|
||||
separated by colons, as described in the <a class="reference internal" href="patterns.html#patterns"><em>Inventory & Patterns</em></a>
|
||||
documentation. The <cite>user</cite> is just the name of the user account:</p>
|
||||
<div class="highlight-python"><pre>---
|
||||
- hosts: webservers
|
||||
user: root</pre>
|
||||
</div>
|
||||
<p>Support for running things from sudo is also available:</p>
|
||||
<div class="highlight-python"><pre>---
|
||||
- hosts: webservers
|
||||
user: yourname
|
||||
sudo: True</pre>
|
||||
</div>
|
||||
<p>You can also login as you, and then sudo to different users than root:</p>
|
||||
<div class="highlight-python"><pre>---
|
||||
- hosts: webservers
|
||||
user: yourname
|
||||
sudo: True
|
||||
sudo_user: postgres</pre>
|
||||
</div>
|
||||
<p>If you need to specify a password to sudo, run <cite>ansible-playbook</cite> with <tt class="docutils literal"><span class="pre">--ask-sudo-pass</span></tt> (<cite>-K</cite>).
|
||||
If you run a sudo playbook and the playbook seems to hang, it’s probably stuck at the sudo prompt.
|
||||
Just <cite>Control-C</cite> to kill it and run it again with <cite>-K</cite>.</p>
|
||||
<div class="admonition important">
|
||||
<p class="first admonition-title">Important</p>
|
||||
<p class="last">When using <cite>sudo_user</cite> to a user other than root, the module
|
||||
arguments are briefly written into a random tempfile in /tmp.
|
||||
These are deleted immediately after the command is executed. This
|
||||
only occurs when sudoing from a user like ‘bob’ to ‘timmy’, not
|
||||
when going from ‘bob’ to ‘root’, or logging in directly as ‘bob’ or
|
||||
‘root’. If this concerns you that this data is briefly readable
|
||||
(not writeable), avoid transferring uncrypted passwords with
|
||||
<cite>sudo_user</cite> set. In other cases, ‘/tmp’ is not used and this does
|
||||
not come into play. Ansible also takes care to not log password
|
||||
parameters.</p>
|
||||
</div>
|
||||
</div>
|
||||
<div class="section" id="vars-section">
|
||||
<h3>Vars section<a class="headerlink" href="#vars-section" title="Permalink to this headline">¶</a></h3>
|
||||
<p>The <cite>vars</cite> section contains a list of variables and values that can be used in the plays, like this:</p>
|
||||
<div class="highlight-python"><pre>---
|
||||
- hosts: webservers
|
||||
user: root
|
||||
vars:
|
||||
http_port: 80
|
||||
van_halen_port: 5150
|
||||
other: 'magic'</pre>
|
||||
</div>
|
||||
<p>These variables can be used later in the playbook like this:</p>
|
||||
<div class="highlight-python"><pre>$varname or ${varname}</pre>
|
||||
</div>
|
||||
<p>The later is useful in the event you need to do something like ${other}_some_string.</p>
|
||||
<p>Inside templates, the full power of the <a class="reference external" href="http://jinja.pocoo.org/docs/">Jinja2</a> templating language is also available, which looks like this:</p>
|
||||
<div class="highlight-python"><pre>{{ varname }}</pre>
|
||||
</div>
|
||||
<p>The Jinja2 documentation provides information about how to construct loops and conditionals for those
|
||||
who which to use more advanced templating. This is optional and the $varname format still works in template
|
||||
files.</p>
|
||||
<p>If there are discovered variables about the system, called ‘facts’, these variables bubble up back into the
|
||||
playbook, and can be used on each system just like explicitly set variables. Ansible provides several
|
||||
of these, prefixed with ‘ansible’, and are documented under ‘setup’ in the module documentation. Additionally,
|
||||
facts can be gathered by ohai and facter if they are installed. Facter variables are prefixed with <tt class="docutils literal"><span class="pre">facter_</span></tt> and Ohai
|
||||
variables are prefixed with <tt class="docutils literal"><span class="pre">ohai_</span></tt>.</p>
|
||||
<p>So for instance, if I wanted
|
||||
to write the hostname into the /etc/motd file, I could say:</p>
|
||||
<div class="highlight-python"><pre>- name: write the motd
|
||||
action: template src=/srv/templates/motd.j2 dest=/etc/motd</pre>
|
||||
</div>
|
||||
<p>And in /srv/templates/motd.j2:</p>
|
||||
<div class="highlight-python"><pre>You are logged into {{ facter_hostname }}</pre>
|
||||
</div>
|
||||
<p>But we’re getting ahead of ourselves. Let’s talk about tasks.</p>
|
||||
</div>
|
||||
<div class="section" id="tasks-list">
|
||||
<h3>Tasks list<a class="headerlink" href="#tasks-list" title="Permalink to this headline">¶</a></h3>
|
||||
<p>Each play contains a list of tasks. Tasks are executed in order, one
|
||||
at a time, against all machines matched by the host pattern,
|
||||
before moving on to the next task. It is important to understand that, within a play,
|
||||
all hosts are going to get the same task directives. It is the purpose of a play to map
|
||||
a selection of hosts to tasks.</p>
|
||||
<p>When running the playbook, which runs top to bottom, hosts with failed tasks are
|
||||
taken out of the rotation for the entire playbook. If things fail, simply correct the playbook file and rerun.</p>
|
||||
<p>The goal of each task is to execute a module, with very specific arguments.
|
||||
Variables, as mentioned above, can be used in arguments to modules.</p>
|
||||
<p>Modules are ‘idempotent’, meaning if you run them
|
||||
again, they will make the changes they are told to make to bring the
|
||||
system to the desired state. This makes it very safe to rerun
|
||||
the same playbook multiple times. They won’t change things
|
||||
unless they have to change things.</p>
|
||||
<p>The <cite>command</cite> and <cite>shell</cite> modules will typically rerun the same command again,
|
||||
which is totally ok if the command is something like
|
||||
‘chmod’ or ‘setsebool’, etc. Though there is a ‘creates’ flag available which can
|
||||
be used to make these modules also idempotent.</p>
|
||||
<p>Every task should have a <cite>name</cite>, which is included in the output from
|
||||
running the playbook. This is output for humans, so it is
|
||||
nice to have reasonably good descriptions of each task step. If the name
|
||||
is not provided though, the string fed to ‘action’ will be used for
|
||||
output.</p>
|
||||
<p>Here is what a basic task looks like, as with most modules,
|
||||
the service module takes key=value arguments:</p>
|
||||
<div class="highlight-python"><pre>tasks:
|
||||
- name: make sure apache is running
|
||||
action: service name=httpd state=running</pre>
|
||||
</div>
|
||||
<p>The <cite>command</cite> and <cite>shell</cite> modules are the one modules that just takes a list
|
||||
of arguments, and don’t use the key=value form. This makes
|
||||
them work just like you would expect. Simple:</p>
|
||||
<div class="highlight-python"><pre>tasks:
|
||||
- name: disable selinux
|
||||
action: command /sbin/setenforce 0</pre>
|
||||
</div>
|
||||
<p>The command and shell module care about return codes, so if you have a command
|
||||
who’s successful exit code is not zero, you may wish to do this:</p>
|
||||
<div class="highlight-python"><pre>tasks:
|
||||
- name: run this command and ignore the result
|
||||
action: shell /usr/bin/somecommand & /bin/true</pre>
|
||||
</div>
|
||||
<p>Variables can be used in action lines. Suppose you defined
|
||||
a variable called ‘vhost’ in the ‘vars’ section, you could do this:</p>
|
||||
<div class="highlight-python"><pre>tasks:
|
||||
- name: create a virtual host file for $vhost
|
||||
action: template src=somefile.j2 dest=/etc/httpd/conf.d/$vhost</pre>
|
||||
</div>
|
||||
<p>Those same variables are usable in templates, which we’ll get to later.</p>
|
||||
<p>Now in a very basic playbook all the tasks will be listed directly in that play, though it will usually
|
||||
make more sense to break up tasks using the ‘include:’ directive. We’ll show that a bit later.</p>
|
||||
</div>
|
||||
</div>
|
||||
<div class="section" id="running-operations-on-change">
|
||||
<h2><a class="toc-backref" href="#contents">Running Operations On Change</a><a class="headerlink" href="#running-operations-on-change" title="Permalink to this headline">¶</a></h2>
|
||||
<p>As we’ve mentioned, modules are written to be ‘idempotent’ and can relay when
|
||||
they have made a change on the remote system. Playbooks recognize this and
|
||||
have a basic event system that can be used to respond to change.</p>
|
||||
<p>These ‘notify’ actions are triggered at the end of each ‘play’ in a playbook, and
|
||||
trigger only once each. For instance, multiple resources may indicate
|
||||
that apache needs to be restarted, but apache will only be bounced once.</p>
|
||||
<p>Here’s an example of restarting two services when the contents of a file
|
||||
change, but only if the file changes:</p>
|
||||
<div class="highlight-python"><pre>- name: template configuration file
|
||||
action: template src=template.j2 dest=/etc/foo.conf
|
||||
notify:
|
||||
- restart memcached
|
||||
- restart apache</pre>
|
||||
</div>
|
||||
<p>The things listed in the ‘notify’ section of a task are called
|
||||
handlers.</p>
|
||||
<p>Handlers are lists of tasks, not really any different from regular
|
||||
tasks, that are referenced by name. Handlers are what notifiers
|
||||
notify. If nothing notifies a handler, it will not run. Regardless
|
||||
of how many things notify a handler, it will run only once, after all
|
||||
of the tasks complete in a particular play.</p>
|
||||
<p>Here’s an example handlers section:</p>
|
||||
<div class="highlight-python"><pre>handlers:
|
||||
- name: restart memcached
|
||||
action: service name=memcached state=restarted
|
||||
- name: restart apache
|
||||
action: service name=apache state=restarted</pre>
|
||||
</div>
|
||||
<p>Handlers are best used to restart services and trigger reboots. You probably
|
||||
won’t need them for much else.</p>
|
||||
<div class="admonition note">
|
||||
<p class="first admonition-title">Note</p>
|
||||
<p class="last">Notify handlers are always run in the order written.</p>
|
||||
</div>
|
||||
</div>
|
||||
<div class="section" id="include-files-and-encouraging-reuse">
|
||||
<h2><a class="toc-backref" href="#contents">Include Files And Encouraging Reuse</a><a class="headerlink" href="#include-files-and-encouraging-reuse" title="Permalink to this headline">¶</a></h2>
|
||||
<p>Suppose you want to reuse lists of tasks between plays or playbooks. You can use
|
||||
include files to do this. Use of included task lists is a great way to define a role
|
||||
that system is going to fulfill. Remember, the goal of a play in a playbook is to map
|
||||
a group of systems into multiple roles. Let’s see what this looks like...</p>
|
||||
<p>A task include file simply contains a flat list of tasks, like so:</p>
|
||||
<div class="highlight-python"><pre>---
|
||||
# possibly saved as tasks/foo.yml
|
||||
- name: placeholder foo
|
||||
action: command /bin/foo
|
||||
- name: placeholder bar
|
||||
action: command /bin/bar</pre>
|
||||
</div>
|
||||
<p>Include directives look like this, and can be mixed in with regular tasks in a playbook:</p>
|
||||
<div class="highlight-python"><pre>tasks:
|
||||
- include: tasks/foo.yml</pre>
|
||||
</div>
|
||||
<p>You can also pass variables into includes. We call this a ‘parameterized include’.</p>
|
||||
<p>For instance, if deploying multiple wordpress instances, I could
|
||||
contain all of my wordpress tasks in a single wordpress.yml file, and use it like so:</p>
|
||||
<div class="highlight-python"><pre>tasks:
|
||||
- include: wordpress.yml user=timmy
|
||||
- include: wordpress.yml user=alice
|
||||
- include: wordpress.yml user=bob</pre>
|
||||
</div>
|
||||
<p>Variables passed in can then be used in the included files. You can reference them like this:</p>
|
||||
<div class="highlight-python"><pre>$user</pre>
|
||||
</div>
|
||||
<p>(In addition to the explicitly passed in parameters, all variables from
|
||||
the vars section are also available for use here as well.)</p>
|
||||
<div class="admonition note">
|
||||
<p class="first admonition-title">Note</p>
|
||||
<p class="last">Task include statements are only usable one-level deep.
|
||||
This means task includes can not include other
|
||||
task includes. This may change in a later release.</p>
|
||||
</div>
|
||||
<p>Includes can also be used in the ‘handlers’ section, for instance, if you
|
||||
want to define how to restart apache, you only have to do that once for all
|
||||
of your playbooks. You might make a handlers.yml that looks like:</p>
|
||||
<div class="highlight-python"><pre>----
|
||||
# this might be in a file like handlers/handlers.yml
|
||||
- name: restart apache
|
||||
action: service name=apache state=restarted</pre>
|
||||
</div>
|
||||
<p>And in your main playbook file, just include it like so, at the bottom
|
||||
of a play:</p>
|
||||
<div class="highlight-python"><pre>handlers:
|
||||
- include: handlers/handlers.yml</pre>
|
||||
</div>
|
||||
<p>You can mix in includes along with your regular non-included tasks and handlers.</p>
|
||||
<p>Includes can also be used to import one playbook file into another. This allows
|
||||
you to define a top-level playbook that is composed of other playbooks.</p>
|
||||
<p>For example:</p>
|
||||
<div class="highlight-python"><pre>- name: this is a play at the top level of a file
|
||||
hosts: all
|
||||
user: root
|
||||
tasks:
|
||||
- name: say hi
|
||||
tags: foo
|
||||
action: shell echo "hi..."
|
||||
|
||||
- include: load_balancers.yml
|
||||
- include: webservers.yml
|
||||
- include: dbservers.yml</pre>
|
||||
</div>
|
||||
<p>Note that you cannot do variable substitution when including one playbook
|
||||
inside another.</p>
|
||||
<div class="admonition note">
|
||||
<p class="first admonition-title">Note</p>
|
||||
<p class="last">You can not conditionally path the location to an include file,
|
||||
like you can with ‘vars_files’. If you find yourself needing to do
|
||||
this, consider how you can restructure your playbook to be more
|
||||
class/role oriented. This is to say you cannot use a ‘fact’ to
|
||||
decide what include file to use. All hosts contained within the
|
||||
play are going to get the same tasks. (‘only_if’ provides some
|
||||
ability for hosts to conditionally skip tasks).</p>
|
||||
</div>
|
||||
</div>
|
||||
<div class="section" id="executing-a-playbook">
|
||||
<h2><a class="toc-backref" href="#contents">Executing A Playbook</a><a class="headerlink" href="#executing-a-playbook" title="Permalink to this headline">¶</a></h2>
|
||||
<p>Now that you’ve learned playbook syntax, how do you run a playbook? It’s simple.
|
||||
Let’s run a playbook using a parallelism level of 10:</p>
|
||||
<div class="highlight-python"><pre>ansible-playbook playbook.yml -f 10</pre>
|
||||
</div>
|
||||
</div>
|
||||
<div class="section" id="tips-and-tricks">
|
||||
<h2><a class="toc-backref" href="#contents">Tips and Tricks</a><a class="headerlink" href="#tips-and-tricks" title="Permalink to this headline">¶</a></h2>
|
||||
<p>Look at the bottom of the playbook execution for a summary of the nodes that were executed
|
||||
and how they performed. General failures and fatal “unreachable” communication attempts are
|
||||
kept seperate in the counts.</p>
|
||||
<p>If you ever want to see detailed output from successful modules as well as unsuccessful ones,
|
||||
use the ‘–verbose’ flag. This is available in Ansible 0.5 and later.</p>
|
||||
<p>Also, in version 0.5 and later, Ansible playbook output is vastly upgraded if the cowsay
|
||||
package is installed. Try it!</p>
|
||||
<p>In version 0.7 and later, to see what hosts would be affected by a playbook before you run it, you
|
||||
can do this:</p>
|
||||
<div class="highlight-python"><pre>ansible-playbook playbook.yml --list-hosts.</pre>
|
||||
</div>
|
||||
<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="YAMLSyntax.html"><em>YAML Syntax</em></a></dt>
|
||||
<dd>Learn about YAML syntax</dd>
|
||||
<dt><a class="reference internal" href=""><em>Playbooks</em></a></dt>
|
||||
<dd>Review the basic Playbook language features</dd>
|
||||
<dt><a class="reference internal" href="playbooks2.html"><em>Advanced Playbooks</em></a></dt>
|
||||
<dd>Learn about Advanced Playbook Features</dd>
|
||||
<dt><a class="reference internal" href="bestpractices.html"><em>Best Practices</em></a></dt>
|
||||
<dd>Various tips about managing playbooks in the real world</dd>
|
||||
<dt><a class="reference internal" href="modules.html"><em>Ansible Modules</em></a></dt>
|
||||
<dd>Learn about available modules</dd>
|
||||
<dt><a class="reference internal" href="moduledev.html"><em>Module Development</em></a></dt>
|
||||
<dd>Learn how to extend Ansible by writing your own modules</dd>
|
||||
<dt><a class="reference internal" href="patterns.html"><em>Inventory & Patterns</em></a></dt>
|
||||
<dd>Learn about how to select hosts</dd>
|
||||
<dt><a class="reference external" href="https://github.com/ansible/ansible/tree/devel/examples/playbooks">Github examples directory</a></dt>
|
||||
<dd>Complete playbook files from the github project source</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>
|
||||
</dl>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
|
||||
<br/>
|
||||
</div>
|
||||
<footer class="footer">
|
||||
<div class="container">
|
||||
<p>
|
||||
<p>
|
||||
© Copyright 2012 Michael DeHaan.<br/>
|
||||
Last updated on Oct 08, 2012.<br/>
|
||||
</p>
|
||||
</div>
|
||||
</footer>
|
||||
</body>
|
||||
</html>
|
||||
@ -0,0 +1,740 @@
|
||||
|
||||
<!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>Advanced Playbooks — Ansible Documentation</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="shortcut icon" href="_static/favicon.ico"/>
|
||||
<link rel="top" title="Ansible Documentation" href="index.html" />
|
||||
<link rel="next" title="Best Practices" href="bestpractices.html" />
|
||||
<link rel="prev" title="Playbooks" href="playbooks.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>
|
||||
|
||||
<script type="text/javascript">
|
||||
(function() {
|
||||
var po = document.createElement('script'); po.type = 'text/javascript'; po.async = true;
|
||||
po.src = 'https://apis.google.com/js/plusone.js';
|
||||
var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(po, s);
|
||||
})();
|
||||
</script>
|
||||
|
||||
<script>(function(d, s, id) {
|
||||
var js, fjs = d.getElementsByTagName(s)[0];
|
||||
if (d.getElementById(id)) return;
|
||||
js = d.createElement(s); js.id = id;
|
||||
js.src = "//connect.facebook.net/en_US/all.js#xfbml=1";
|
||||
fjs.parentNode.insertBefore(js, fjs);
|
||||
}(document, 'script', 'facebook-jssdk'));</script>
|
||||
|
||||
</head>
|
||||
<body>
|
||||
<div class="topbar" data-scrollspy="scrollspy" >
|
||||
<div class="topbar-inner">
|
||||
<div class="container">
|
||||
<a class="brand" href="index.html">Ansible Documentation</a>
|
||||
<ul class="nav">
|
||||
|
||||
<li><a href="/">Home</A>
|
||||
<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">Getting Started</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="patterns.html">Inventory & Patterns</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="examples.html">Command Line Examples And Next Steps</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 current"><a class="current reference internal" href="">Advanced Playbooks</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="bestpractices.html">Best Practices</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="api.html">API & Integrations</a></li>
|
||||
<li class="toctree-l1"><a class="reference internal" href="moduledev.html">Module Development</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="#">Advanced Playbooks</a><ul>
|
||||
<li><a class="reference internal" href="#tags">Tags</a></li>
|
||||
<li><a class="reference internal" href="#playbooks-including-playbooks">Playbooks Including Playbooks</a></li>
|
||||
<li><a class="reference internal" href="#ignoring-failed-commands">Ignoring Failed Commands</a></li>
|
||||
<li><a class="reference internal" href="#accessing-complex-variable-data">Accessing Complex Variable Data</a></li>
|
||||
<li><a class="reference internal" href="#accessing-information-about-other-hosts">Accessing Information About Other Hosts</a></li>
|
||||
<li><a class="reference internal" href="#variable-file-seperation">Variable File Seperation</a></li>
|
||||
<li><a class="reference internal" href="#prompting-for-sensitive-data">Prompting For Sensitive Data</a></li>
|
||||
<li><a class="reference internal" href="#passing-variables-on-the-command-line">Passing Variables On The Command Line</a></li>
|
||||
<li><a class="reference internal" href="#conditional-execution">Conditional Execution</a></li>
|
||||
<li><a class="reference internal" href="#conditional-imports">Conditional Imports</a></li>
|
||||
<li><a class="reference internal" href="#loops">Loops</a></li>
|
||||
<li><a class="reference internal" href="#selecting-files-and-templates-based-on-variables">Selecting Files And Templates Based On Variables</a></li>
|
||||
<li><a class="reference internal" href="#asynchronous-actions-and-polling">Asynchronous Actions and Polling</a></li>
|
||||
<li><a class="reference internal" href="#local-playbooks">Local Playbooks</a></li>
|
||||
<li><a class="reference internal" href="#turning-off-facts">Turning Off Facts</a></li>
|
||||
<li><a class="reference internal" href="#pull-mode-playbooks">Pull-Mode Playbooks</a></li>
|
||||
<li><a class="reference internal" href="#register-variables">Register Variables</a></li>
|
||||
<li><a class="reference internal" href="#rolling-updates">Rolling Updates</a></li>
|
||||
<li><a class="reference internal" href="#delegation">Delegation</a></li>
|
||||
<li><a class="reference internal" href="#understanding-variable-precedence">Understanding Variable Precedence</a></li>
|
||||
<li><a class="reference internal" href="#style-points">Style Points</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="advanced-playbooks">
|
||||
<h1><a class="toc-backref" href="#contents">Advanced Playbooks</a><a class="headerlink" href="#advanced-playbooks" title="Permalink to this headline">¶</a></h1>
|
||||
<p>Here are some advanced features of the playbooks language. Using all of these features
|
||||
are not neccessary, but many of them will prove useful. If a feature doesn’t seem immediately
|
||||
relevant, feel free to skip it. For many people, the features documented in <cite>playbooks</cite> will
|
||||
be 90% or more of what they use in Ansible.</p>
|
||||
<div class="contents topic" id="contents">
|
||||
<p class="topic-title first">Contents</p>
|
||||
<ul class="simple">
|
||||
<li><a class="reference internal" href="#advanced-playbooks" id="id1">Advanced Playbooks</a><ul>
|
||||
<li><a class="reference internal" href="#tags" id="id2">Tags</a></li>
|
||||
<li><a class="reference internal" href="#playbooks-including-playbooks" id="id3">Playbooks Including Playbooks</a></li>
|
||||
<li><a class="reference internal" href="#ignoring-failed-commands" id="id4">Ignoring Failed Commands</a></li>
|
||||
<li><a class="reference internal" href="#accessing-complex-variable-data" id="id5">Accessing Complex Variable Data</a></li>
|
||||
<li><a class="reference internal" href="#accessing-information-about-other-hosts" id="id6">Accessing Information About Other Hosts</a></li>
|
||||
<li><a class="reference internal" href="#variable-file-seperation" id="id7">Variable File Seperation</a></li>
|
||||
<li><a class="reference internal" href="#prompting-for-sensitive-data" id="id8">Prompting For Sensitive Data</a></li>
|
||||
<li><a class="reference internal" href="#passing-variables-on-the-command-line" id="id9">Passing Variables On The Command Line</a></li>
|
||||
<li><a class="reference internal" href="#conditional-execution" id="id10">Conditional Execution</a></li>
|
||||
<li><a class="reference internal" href="#conditional-imports" id="id11">Conditional Imports</a></li>
|
||||
<li><a class="reference internal" href="#loops" id="id12">Loops</a></li>
|
||||
<li><a class="reference internal" href="#selecting-files-and-templates-based-on-variables" id="id13">Selecting Files And Templates Based On Variables</a></li>
|
||||
<li><a class="reference internal" href="#asynchronous-actions-and-polling" id="id14">Asynchronous Actions and Polling</a></li>
|
||||
<li><a class="reference internal" href="#local-playbooks" id="id15">Local Playbooks</a></li>
|
||||
<li><a class="reference internal" href="#turning-off-facts" id="id16">Turning Off Facts</a></li>
|
||||
<li><a class="reference internal" href="#pull-mode-playbooks" id="id17">Pull-Mode Playbooks</a></li>
|
||||
<li><a class="reference internal" href="#register-variables" id="id18">Register Variables</a></li>
|
||||
<li><a class="reference internal" href="#rolling-updates" id="id19">Rolling Updates</a></li>
|
||||
<li><a class="reference internal" href="#delegation" id="id20">Delegation</a></li>
|
||||
<li><a class="reference internal" href="#understanding-variable-precedence" id="id21">Understanding Variable Precedence</a></li>
|
||||
<li><a class="reference internal" href="#style-points" id="id22">Style Points</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
</ul>
|
||||
</div>
|
||||
<div class="section" id="tags">
|
||||
<h2><a class="toc-backref" href="#contents">Tags</a><a class="headerlink" href="#tags" title="Permalink to this headline">¶</a></h2>
|
||||
<p class="versionadded">
|
||||
<span class="versionmodified">New in version 0.6.</span></p>
|
||||
<p>If you have a large playbook it may become useful to be able to run a
|
||||
specific part of the configuration. Both plays and tasks support a
|
||||
“tags:” attribute for this reason.</p>
|
||||
<p>Example:</p>
|
||||
<div class="highlight-python"><pre>tasks:
|
||||
|
||||
- action: yum name=$item state=installed
|
||||
with_items:
|
||||
- httpd
|
||||
- memcached
|
||||
tags:
|
||||
- packages
|
||||
|
||||
- action: template src=templates/src.j2 dest=/etc/foo.conf
|
||||
tags:
|
||||
- configuration</pre>
|
||||
</div>
|
||||
<p>If you wanted to just run the “configuration” and “packages” part of a very long playbook, you could do this:</p>
|
||||
<div class="highlight-python"><pre>ansible-playbook example.yml --tags "configuration,packages"</pre>
|
||||
</div>
|
||||
</div>
|
||||
<div class="section" id="playbooks-including-playbooks">
|
||||
<h2><a class="toc-backref" href="#contents">Playbooks Including Playbooks</a><a class="headerlink" href="#playbooks-including-playbooks" title="Permalink to this headline">¶</a></h2>
|
||||
<p class="versionadded">
|
||||
<span class="versionmodified">New in version 0.6.</span></p>
|
||||
<p>To further advance the concept of include files, playbook files can
|
||||
include other playbook files. Suppose you define the behavior of all
|
||||
your webservers in “webservers.yml” and all your database servers in
|
||||
“dbservers.yml”. You can create a “site.yml” that would reconfigure
|
||||
all of your systems like this:</p>
|
||||
<div class="highlight-python"><pre>----
|
||||
- include: playbooks/webservers.yml
|
||||
- include: playbooks/dbservers.yml</pre>
|
||||
</div>
|
||||
<p>This concept works great with tags to rapidly select exactly what plays you want to run, and exactly
|
||||
what parts of those plays.</p>
|
||||
</div>
|
||||
<div class="section" id="ignoring-failed-commands">
|
||||
<h2><a class="toc-backref" href="#contents">Ignoring Failed Commands</a><a class="headerlink" href="#ignoring-failed-commands" title="Permalink to this headline">¶</a></h2>
|
||||
<p class="deprecated">
|
||||
<span class="versionmodified">Deprecated since version 0.6.</span></p>
|
||||
<p>Generally playbooks will stop executing any more steps on a host that
|
||||
has a failure. Sometimes, though, you want to continue on. To do so,
|
||||
write a task that looks like this:</p>
|
||||
<div class="highlight-python"><pre>- name: this will not be counted as a failure
|
||||
action: command /bin/false
|
||||
ignore_errors: True</pre>
|
||||
</div>
|
||||
</div>
|
||||
<div class="section" id="accessing-complex-variable-data">
|
||||
<h2><a class="toc-backref" href="#contents">Accessing Complex Variable Data</a><a class="headerlink" href="#accessing-complex-variable-data" title="Permalink to this headline">¶</a></h2>
|
||||
<p>Some provided facts, like networking information, are made available as nested data structures. To access
|
||||
them a simple ‘$foo’ is not sufficient, but it is still easy to do. Here’s how we get an IP address:</p>
|
||||
<div class="highlight-python"><pre>${ansible_eth0.ipv4.address}</pre>
|
||||
</div>
|
||||
<p>It is also possible to access variables whose elements are arrays:</p>
|
||||
<div class="highlight-python"><pre>${somelist[0]}</pre>
|
||||
</div>
|
||||
<p>And the array and hash reference syntaxes can be mixed.</p>
|
||||
<p>In templates, the simple access form still holds, but they can also be accessed from Jinja2 in more Python-native ways if
|
||||
that is preferred:</p>
|
||||
<div class="highlight-python"><pre>{{ ansible_eth0["ipv4"]["address"] }}</pre>
|
||||
</div>
|
||||
</div>
|
||||
<div class="section" id="accessing-information-about-other-hosts">
|
||||
<h2><a class="toc-backref" href="#contents">Accessing Information About Other Hosts</a><a class="headerlink" href="#accessing-information-about-other-hosts" title="Permalink to this headline">¶</a></h2>
|
||||
<p>If your database server wants to check the value of a ‘fact’ from another node, or an inventory variable
|
||||
assigned to another node, it’s easy to do so within a template or even an action line:</p>
|
||||
<div class="highlight-python"><pre>${hostvars.hostname.factname}</pre>
|
||||
</div>
|
||||
<div class="admonition note">
|
||||
<p class="first admonition-title">Note</p>
|
||||
<p class="last">No database or other complex system is required to exchange data
|
||||
between hosts. The hosts that you want to reference data from must
|
||||
be included in either the current play or any previous play.</p>
|
||||
</div>
|
||||
<p>Additionally, <em>group_names</em> is a list (array) of all the groups the current host is in. This can be used in templates using Jinja2 syntax to make template source files that vary based on the group membership (or role) of the host:</p>
|
||||
<div class="highlight-python"><pre>{% if 'webserver' in group_names %}
|
||||
# some part of a configuration file that only applies to webservers
|
||||
{% endif %}</pre>
|
||||
</div>
|
||||
<p><em>groups</em> is a list of all the groups (and hosts) in the inventory. This can be used to enumerate all hosts within a group.
|
||||
For example:</p>
|
||||
<div class="highlight-python"><pre>{% for host in groups['app_servers'] %}
|
||||
# something that applies to all app servers.
|
||||
{% endfor %}</pre>
|
||||
</div>
|
||||
<p>Use cases include pointing a frontend proxy server to all of the app servers, setting up the correct firewall rules between servers, etc.</p>
|
||||
<p><em>inventory_hostname</em> is the name of the hostname as configured in Ansible’s inventory host file. This can
|
||||
be useful for when you don’t want to rely on the discovered hostname <cite>ansible_hostname</cite> or for other mysterious
|
||||
reasons. If you have a long FQDN, <em>inventory_hostname_short</em> (in Ansible 0.6) also contains the part up to the first
|
||||
period.</p>
|
||||
<p>Don’t worry about any of this unless you think you need it. You’ll know when you do.</p>
|
||||
</div>
|
||||
<div class="section" id="variable-file-seperation">
|
||||
<h2><a class="toc-backref" href="#contents">Variable File Seperation</a><a class="headerlink" href="#variable-file-seperation" title="Permalink to this headline">¶</a></h2>
|
||||
<p>It’s a great idea to keep your playbooks under source control, but
|
||||
you may wish to make the playbook source public while keeping certain
|
||||
important variables private. Similarly, sometimes you may just
|
||||
want to keep certain information in different files, away from
|
||||
the main playbook.</p>
|
||||
<p>You can do this by using an external variables file, or files, just like this:</p>
|
||||
<div class="highlight-python"><pre>---
|
||||
- hosts: all
|
||||
user: root
|
||||
vars:
|
||||
favcolor: blue
|
||||
vars_files:
|
||||
- /vars/external_vars.yml
|
||||
tasks:
|
||||
- name: this is just a placeholder
|
||||
action: command /bin/echo foo</pre>
|
||||
</div>
|
||||
<p>This removes the risk of sharing sensitive data with others when
|
||||
sharing your playbook source with them.</p>
|
||||
<p>The contents of each variables file is a simple YAML dictionary, like this:</p>
|
||||
<div class="highlight-python"><pre>---
|
||||
# in the above example, this would be vars/external_vars.yml
|
||||
somevar: somevalue
|
||||
password: magic</pre>
|
||||
</div>
|
||||
<div class="admonition note">
|
||||
<p class="first admonition-title">Note</p>
|
||||
<p class="last">It’s also possible to keep per-host and per-group variables in very
|
||||
similar files, this is covered in <a class="reference internal" href="patterns.html#patterns"><em>Inventory & Patterns</em></a>.</p>
|
||||
</div>
|
||||
</div>
|
||||
<div class="section" id="prompting-for-sensitive-data">
|
||||
<h2><a class="toc-backref" href="#contents">Prompting For Sensitive Data</a><a class="headerlink" href="#prompting-for-sensitive-data" title="Permalink to this headline">¶</a></h2>
|
||||
<p>You may wish to prompt the user for certain input, and can
|
||||
do so with the similarly named ‘vars_prompt’ section. This has uses
|
||||
beyond security, for instance, you may use the same playbook for all
|
||||
software releases and would prompt for a particular release version
|
||||
in a push-script:</p>
|
||||
<div class="highlight-python"><pre>---
|
||||
- hosts: all
|
||||
user: root
|
||||
vars:
|
||||
from: "camelot"
|
||||
vars_prompt:
|
||||
name: "what is your name?"
|
||||
quest: "what is your quest?"
|
||||
favcolor: "what is your favorite color?"</pre>
|
||||
</div>
|
||||
<p>There are full examples of both of these items in the github examples/playbooks directory.</p>
|
||||
<p>An alternative form of vars_prompt allows for hiding input from the user, and may later support
|
||||
some other options, but otherwise works equivalently:</p>
|
||||
<div class="highlight-python"><pre>vars_prompt:
|
||||
- name: "some_password"
|
||||
prompt: "Enter password"
|
||||
private: True
|
||||
- name: "release_version"
|
||||
prompt: "Product release version"
|
||||
private: False</pre>
|
||||
</div>
|
||||
</div>
|
||||
<div class="section" id="passing-variables-on-the-command-line">
|
||||
<h2><a class="toc-backref" href="#contents">Passing Variables On The Command Line</a><a class="headerlink" href="#passing-variables-on-the-command-line" title="Permalink to this headline">¶</a></h2>
|
||||
<p>In addition to <cite>vars_prompt</cite> and <cite>vars_files</cite>, it is possible to send variables over
|
||||
the ansible command line. This is particularly useful when writing a generic release playbook
|
||||
where you may want to pass in the version of the application to deploy:</p>
|
||||
<div class="highlight-python"><pre>ansible-playbook release.yml --extra-vars "version=1.23.45 other_variable=foo"</pre>
|
||||
</div>
|
||||
<p>This is useful, for, among other things, setting the hosts group or the user for the playbook.</p>
|
||||
<p>Example:</p>
|
||||
<div class="highlight-python"><pre>-----
|
||||
- user: $user
|
||||
hosts: $hosts
|
||||
tasks:
|
||||
- ...
|
||||
|
||||
ansible-playbook release.yml --extra-vars "hosts=vipers user=starbuck"</pre>
|
||||
</div>
|
||||
</div>
|
||||
<div class="section" id="conditional-execution">
|
||||
<h2><a class="toc-backref" href="#contents">Conditional Execution</a><a class="headerlink" href="#conditional-execution" title="Permalink to this headline">¶</a></h2>
|
||||
<p>Sometimes you will want to skip a particular step on a particular host. This could be something
|
||||
as simple as not installing a certain package if the operating system is a particular version,
|
||||
or it could be something like performing some cleanup steps if a filesystem is getting full.</p>
|
||||
<p>This is easy to do in Ansible, with the <cite>only_if</cite> clause, which actually is a Python expression.
|
||||
Don’t panic – it’s actually pretty simple:</p>
|
||||
<div class="highlight-python"><pre>vars:
|
||||
favcolor: blue
|
||||
is_favcolor_blue: "'$favcolor' == 'blue'"
|
||||
is_centos: "'$facter_operatingsystem' == 'CentOS'"
|
||||
|
||||
tasks:
|
||||
- name: "shutdown if my favorite color is blue"
|
||||
action: command /sbin/shutdown -t now
|
||||
only_if: '$is_favcolor_blue'</pre>
|
||||
</div>
|
||||
<p>Variables from tools like <cite>facter</cite> and <cite>ohai</cite> can be used here, if installed, or you can
|
||||
use variables that bubble up from ansible, which many are provided by the <a class="reference internal" href="modules.html#setup"><em>setup</em></a> module. As a reminder,
|
||||
these variables are prefixed, so it’s <cite>$facter_operatingsystem</cite>, not <cite>$operatingsystem</cite>. Ansible’s
|
||||
built in variables are prefixed with <cite>ansible_</cite>.</p>
|
||||
<p>The only_if expression is actually a tiny small bit of Python, so be sure to quote variables and make something
|
||||
that evaluates to <cite>True</cite> or <cite>False</cite>. It is a good idea to use ‘vars_files’ instead of ‘vars’ to define
|
||||
all of your conditional expressions in a way that makes them very easy to reuse between plays
|
||||
and playbooks.</p>
|
||||
<p>You cannot use live checks here, like ‘os.path.exists’, so don’t try.</p>
|
||||
<p>It’s also easy to provide your own facts if you want, which is covered in <a class="reference internal" href="moduledev.html"><em>Module Development</em></a>. To run them, just
|
||||
make a call to your own custom fact gathering module at the top of your list of tasks, and variables returned
|
||||
there will be accessible to future tasks:</p>
|
||||
<div class="highlight-python"><pre>tasks:
|
||||
- name: gather site specific fact data
|
||||
action: site_facts
|
||||
- action: command echo ${my_custom_fact_can_be_used_now}</pre>
|
||||
</div>
|
||||
</div>
|
||||
<div class="section" id="conditional-imports">
|
||||
<h2><a class="toc-backref" href="#contents">Conditional Imports</a><a class="headerlink" href="#conditional-imports" title="Permalink to this headline">¶</a></h2>
|
||||
<p>Sometimes you will want to do certain things differently in a playbook based on certain criteria.
|
||||
Having one playbook that works on multiple platforms and OS versions is a good example.</p>
|
||||
<p>As an example, the name of the Apache package may be different between CentOS and Debian,
|
||||
but it is easily handled with a minimum of syntax in an Ansible Playbook:</p>
|
||||
<div class="highlight-python"><pre>---
|
||||
- hosts: all
|
||||
user: root
|
||||
vars_files:
|
||||
- "vars/common.yml"
|
||||
- [ "vars/$facter_operatingsystem.yml", "vars/os_defaults.yml" ]
|
||||
tasks:
|
||||
- name: make sure apache is running
|
||||
action: service name=$apache state=running</pre>
|
||||
</div>
|
||||
<div class="admonition note">
|
||||
<p class="first admonition-title">Note</p>
|
||||
<p class="last">The variable (<cite>$facter_operatingsystem</cite>) is being interpolated into
|
||||
the list of filenames being defined for vars_files.</p>
|
||||
</div>
|
||||
<p>As a reminder, the various YAML files contain just keys and values:</p>
|
||||
<div class="highlight-python"><pre>---
|
||||
# for vars/CentOS.yml
|
||||
apache: httpd
|
||||
somethingelse: 42</pre>
|
||||
</div>
|
||||
<p>How does this work? If the operating system was ‘CentOS’, the first file Ansible would try to import
|
||||
would be ‘vars/CentOS.yml’, followed up by ‘/vars/os_defaults.yml’ if that file
|
||||
did not exist. If no files in the list were found, an error would be raised.
|
||||
On Debian, it would instead first look towards ‘vars/Debian.yml’ instead of ‘vars/CentOS.yml’, before
|
||||
falling back on ‘vars/os_defaults.yml’. Pretty simple.</p>
|
||||
<p>To use this conditional import feature, you’ll need facter or ohai installed prior to running the playbook, but
|
||||
you can of course push this out with Ansible if you like:</p>
|
||||
<div class="highlight-python"><pre># for facter
|
||||
ansible -m yum -a "pkg=facter ensure=installed"
|
||||
ansible -m yum -a "pkg=ruby-json ensure=installed"
|
||||
|
||||
# for ohai
|
||||
ansible -m yum -a "pkg=ohai ensure=installed"</pre>
|
||||
</div>
|
||||
<p>Ansible’s approach to configuration – seperating variables from tasks, keeps your playbooks
|
||||
from turning into arbitrary code with ugly nested ifs, conditionals, and so on - and results
|
||||
in more streamlined & auditable configuration rules – especially because there are a
|
||||
minimum of decision points to track.</p>
|
||||
</div>
|
||||
<div class="section" id="loops">
|
||||
<h2><a class="toc-backref" href="#contents">Loops</a><a class="headerlink" href="#loops" title="Permalink to this headline">¶</a></h2>
|
||||
<p>To save some typing, repeated tasks can be written in short-hand like so:</p>
|
||||
<div class="highlight-python"><pre>- name: add user $item
|
||||
action: user name=$item state=present groups=wheel
|
||||
with_items:
|
||||
- testuser1
|
||||
- testuser2</pre>
|
||||
</div>
|
||||
<p>If you have defined a YAML list in a variables file, or the ‘vars’ section, you can also do:</p>
|
||||
<div class="highlight-python"><pre>with_items: $somelist</pre>
|
||||
</div>
|
||||
<p>The above would be the equivalent of:</p>
|
||||
<div class="highlight-python"><pre>- name: add user testuser1
|
||||
action: user name=testuser1 state=present groups=wheel
|
||||
- name: add user testuser2
|
||||
action: user name=testuser2 state=present groups=wheel</pre>
|
||||
</div>
|
||||
<p>The yum and apt modules use with_items to execute fewer package manager transactions.</p>
|
||||
</div>
|
||||
<div class="section" id="selecting-files-and-templates-based-on-variables">
|
||||
<h2><a class="toc-backref" href="#contents">Selecting Files And Templates Based On Variables</a><a class="headerlink" href="#selecting-files-and-templates-based-on-variables" title="Permalink to this headline">¶</a></h2>
|
||||
<p>Sometimes a configuration file you want to copy, or a template you will use may depend on a variable.
|
||||
The following construct selects the first available file appropriate for the variables of a given host,
|
||||
which is often much cleaner than putting a lot of if conditionals in a template.</p>
|
||||
<p>The following example shows how to template out a configuration file that was very different between, say,
|
||||
CentOS and Debian:</p>
|
||||
<div class="highlight-python"><pre>- name: template a file
|
||||
action: template src=$item dest=/etc/myapp/foo.conf
|
||||
first_available_file:
|
||||
- /srv/templates/myapp/${ansible_distribution}.conf
|
||||
- /srv/templates/myapp/default.conf</pre>
|
||||
</div>
|
||||
</div>
|
||||
<div class="section" id="asynchronous-actions-and-polling">
|
||||
<h2><a class="toc-backref" href="#contents">Asynchronous Actions and Polling</a><a class="headerlink" href="#asynchronous-actions-and-polling" title="Permalink to this headline">¶</a></h2>
|
||||
<p>By default tasks in playbooks block, meaning the connections stay open
|
||||
until the task is done on each node. If executing playbooks with
|
||||
a small parallelism value (aka <tt class="docutils literal"><span class="pre">--forks</span></tt>), you may wish that long
|
||||
running operations can go faster. The easiest way to do this is
|
||||
to kick them off all at once and then poll until they are done.</p>
|
||||
<p>You will also want to use asynchronous mode on very long running
|
||||
operations that might be subject to timeout.</p>
|
||||
<p>To launch a task asynchronously, specify its maximum runtime
|
||||
and how frequently you would like to poll for status. The default
|
||||
poll value is 10 seconds if you do not specify a value for <cite>poll</cite>:</p>
|
||||
<div class="highlight-python"><pre>---
|
||||
- hosts: all
|
||||
user: root
|
||||
tasks:
|
||||
- name: simulate long running op (15 sec), wait for up to 45, poll every 5
|
||||
action: command /bin/sleep 15
|
||||
async: 45
|
||||
poll: 5</pre>
|
||||
</div>
|
||||
<div class="admonition note">
|
||||
<p class="first admonition-title">Note</p>
|
||||
<p class="last">There is no default for the async time limit. If you leave off the
|
||||
‘async’ keyword, the task runs synchronously, which is Ansible’s
|
||||
default.</p>
|
||||
</div>
|
||||
<p>Alternatively, if you do not need to wait on the task to complete, you may
|
||||
“fire and forget” by specifying a poll value of 0:</p>
|
||||
<div class="highlight-python"><pre>---
|
||||
- hosts: all
|
||||
user: root
|
||||
tasks:
|
||||
- name: simulate long running op, allow to run for 45, fire and forget
|
||||
action: command /bin/sleep 15
|
||||
async: 45
|
||||
poll: 0</pre>
|
||||
</div>
|
||||
<div class="admonition note">
|
||||
<p class="first admonition-title">Note</p>
|
||||
<p class="last">You shouldn’t “fire and forget” with operations that require
|
||||
exclusive locks, such as yum transactions, if you expect to run other
|
||||
commands later in the playbook against those same resources.</p>
|
||||
</div>
|
||||
<div class="admonition note">
|
||||
<p class="first admonition-title">Note</p>
|
||||
<p class="last">Using a higher value for <tt class="docutils literal"><span class="pre">--forks</span></tt> will result in kicking off asynchronous
|
||||
tasks even faster. This also increases the efficiency of polling.</p>
|
||||
</div>
|
||||
</div>
|
||||
<div class="section" id="local-playbooks">
|
||||
<h2><a class="toc-backref" href="#contents">Local Playbooks</a><a class="headerlink" href="#local-playbooks" title="Permalink to this headline">¶</a></h2>
|
||||
<p>It may be useful to use a playbook locally, rather than by connecting over SSH. This can be useful
|
||||
for assuring the configuration of a system by putting a playbook on a crontab. This may also be used
|
||||
to run a playbook inside a OS installer, such as an Anaconda kickstart.</p>
|
||||
<p>To run an entire playbook locally, just set the “hosts:” line to “hosts:127.0.0.1” and then run the playbook like so:</p>
|
||||
<div class="highlight-python"><pre>ansible-playbook playbook.yml --connection=local</pre>
|
||||
</div>
|
||||
<p>Alternatively, a local connection can be used in a single playbook play, even if other plays in the playbook
|
||||
use the default remote connection type:</p>
|
||||
<div class="highlight-python"><pre>hosts: 127.0.0.1
|
||||
connection: local</pre>
|
||||
</div>
|
||||
</div>
|
||||
<div class="section" id="turning-off-facts">
|
||||
<h2><a class="toc-backref" href="#contents">Turning Off Facts</a><a class="headerlink" href="#turning-off-facts" title="Permalink to this headline">¶</a></h2>
|
||||
<p>If you know you don’t need any fact data about your hosts, and know everything about your systems centrally, you
|
||||
can turn off fact gathering. This has advantages in scaling ansible in push mode with very large numbers of
|
||||
systems, mainly, or if you are using Ansible on experimental platforms. In any play, just do this:</p>
|
||||
<div class="highlight-python"><pre>- hosts: whatever
|
||||
gather_facts: False</pre>
|
||||
</div>
|
||||
</div>
|
||||
<div class="section" id="pull-mode-playbooks">
|
||||
<h2><a class="toc-backref" href="#contents">Pull-Mode Playbooks</a><a class="headerlink" href="#pull-mode-playbooks" title="Permalink to this headline">¶</a></h2>
|
||||
<p>The use of playbooks in local mode (above) is made extremely powerful with the addition of <cite>ansible-pull</cite>.
|
||||
A script for setting up ansible-pull is provided in the examples/playbooks directory of the source
|
||||
checkout.</p>
|
||||
<p>The basic idea is to use Ansible to set up a remote copy of ansible on each managed node, each set to run via
|
||||
cron and update playbook source via git. This interverts the default push architecture of ansible into a pull
|
||||
architecture, which has near-limitless scaling potential. The setup playbook can be tuned to change
|
||||
the cron frequency, logging locations, and parameters to ansible-pull.</p>
|
||||
<p>This is useful both for extreme scale-out as well as periodic remediation. Usage of the ‘fetch’ module to retrieve
|
||||
logs from ansible-pull runs would be an excellent way to gather and analyze remote logs from ansible-pull.</p>
|
||||
</div>
|
||||
<div class="section" id="register-variables">
|
||||
<h2><a class="toc-backref" href="#contents">Register Variables</a><a class="headerlink" href="#register-variables" title="Permalink to this headline">¶</a></h2>
|
||||
<p class="versionadded">
|
||||
<span class="versionmodified">New in version 0.7.</span></p>
|
||||
<p>Often in a playbook it may be useful to store the result of a given command in a variable and access
|
||||
it later. Use of the command module in this way can in many ways eliminate the need to write site specific facts, for
|
||||
instance, you could test for the existance of a particular program.</p>
|
||||
<p>The ‘register’ keyword decides what variable to save a result in. The resulting variables can be used in templates, action lines, or only_if statements. It looks like this (in an obviously trivial example):</p>
|
||||
<div class="highlight-python"><pre>- name: test play
|
||||
hosts: all
|
||||
|
||||
tasks:
|
||||
|
||||
- action: shell cat /etc/motd
|
||||
register: motd_contents
|
||||
|
||||
- action: shell echo "motd contains the word hi"
|
||||
only_if: "'${motd_contents.stdout}'.find('hi') != -1"</pre>
|
||||
</div>
|
||||
</div>
|
||||
<div class="section" id="rolling-updates">
|
||||
<h2><a class="toc-backref" href="#contents">Rolling Updates</a><a class="headerlink" href="#rolling-updates" title="Permalink to this headline">¶</a></h2>
|
||||
<p class="versionadded">
|
||||
<span class="versionmodified">New in version 0.7.</span></p>
|
||||
<p>By default ansible will try to manage all of the machines referenced in a play in parallel. For a rolling updates
|
||||
use case, you can define how many hosts ansible should manage at a single time by using the ‘’serial’’ keyword:</p>
|
||||
<div class="highlight-python"><pre>- name: test play
|
||||
hosts: webservers
|
||||
serial: 3</pre>
|
||||
</div>
|
||||
<p>In the above example, if we had 100 hosts, 3 hosts in the group ‘webservers’
|
||||
would complete the play completely before moving on to the next 3 hosts.</p>
|
||||
</div>
|
||||
<div class="section" id="delegation">
|
||||
<h2><a class="toc-backref" href="#contents">Delegation</a><a class="headerlink" href="#delegation" title="Permalink to this headline">¶</a></h2>
|
||||
<p class="versionadded">
|
||||
<span class="versionmodified">New in version 0.7.</span></p>
|
||||
<p>If you want to perform a task on one host with reference to other hosts, use the ‘delegate_to’ keyword on a task.
|
||||
This is ideal for placing nodes in a load balanced pool, or removing them. It is also very useful for controlling
|
||||
outage windows. Using this with the ‘serial’ keyword to control the number of hosts executing at one time is also
|
||||
a good idea:</p>
|
||||
<div class="highlight-python"><pre>---
|
||||
- hosts: webservers
|
||||
serial: 5
|
||||
|
||||
tasks:
|
||||
- name: take out of load balancer pool
|
||||
action: command /usr/bin/take_out_of_pool $inventory_hostname
|
||||
delegate_to: 127.0.0.1
|
||||
|
||||
- name: actual steps would go here
|
||||
action: yum name=acme-web-stack state=latest
|
||||
|
||||
- name: add back to load balancer pool
|
||||
action: command /usr/bin/add_back_to_pool $inventory_hostname
|
||||
delegate_to: 127.0.0.1</pre>
|
||||
</div>
|
||||
<p>Here is the same playbook as above, but using the shorthand syntax,
|
||||
‘local_action’, for delegating to 127.0.0.1:</p>
|
||||
<div class="highlight-python"><pre>---
|
||||
# ...
|
||||
tasks:
|
||||
- name: take out of load balancer pool
|
||||
local_action: command /usr/bin/take_out_of_pool $inventory_hostname
|
||||
|
||||
# ...
|
||||
|
||||
- name: add back to load balancer pool
|
||||
local_action: command /usr/bin/add_back_to_pool $inventory_hostname</pre>
|
||||
</div>
|
||||
</div>
|
||||
<div class="section" id="understanding-variable-precedence">
|
||||
<h2><a class="toc-backref" href="#contents">Understanding Variable Precedence</a><a class="headerlink" href="#understanding-variable-precedence" title="Permalink to this headline">¶</a></h2>
|
||||
<p>You have already learned about inventory host and group variables, ‘vars’, and ‘vars_files’.</p>
|
||||
<p>If a variable name is defined in more than one place with the same name, priority is as follows
|
||||
to determine which place sets the value of the variable.</p>
|
||||
<ol class="arabic simple">
|
||||
<li>Variables loaded from YAML files mentioned in ‘vars_files’ in a playbook.</li>
|
||||
<li>‘vars’ as defined in the playbook.</li>
|
||||
<li>facts, whether built in or custom, or variables assigned from the ‘register’ keyword.</li>
|
||||
<li>variables passed to parameterized task include statements.</li>
|
||||
<li>Host variables from inventory.</li>
|
||||
<li>Group variables from inventory, in order of least specific group to most specific.</li>
|
||||
</ol>
|
||||
<p>Therefore, if you want to set a default value for something you wish to override somewhere else, the best
|
||||
place to set such a default is in a group variable.</p>
|
||||
</div>
|
||||
<div class="section" id="style-points">
|
||||
<h2><a class="toc-backref" href="#contents">Style Points</a><a class="headerlink" href="#style-points" title="Permalink to this headline">¶</a></h2>
|
||||
<p>Ansible playbooks are colorized. If you do not like this, set the ANSIBLE_NOCOLOR=1 environment variable.</p>
|
||||
<p>Ansible playbooks also look more impressive with cowsay installed, and we encourage installing this package.</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="YAMLSyntax.html"><em>YAML Syntax</em></a></dt>
|
||||
<dd>Learn about YAML syntax</dd>
|
||||
<dt><a class="reference internal" href="playbooks.html"><em>Playbooks</em></a></dt>
|
||||
<dd>Review the basic playbook features</dd>
|
||||
<dt><a class="reference internal" href="bestpractices.html"><em>Best Practices</em></a></dt>
|
||||
<dd>Various tips about playbooks in the real world</dd>
|
||||
<dt><a class="reference internal" href="modules.html"><em>Ansible Modules</em></a></dt>
|
||||
<dd>Learn about available modules</dd>
|
||||
<dt><a class="reference internal" href="moduledev.html"><em>Module Development</em></a></dt>
|
||||
<dd>Learn how to extend Ansible by writing your own modules</dd>
|
||||
<dt><a class="reference internal" href="patterns.html"><em>Inventory & Patterns</em></a></dt>
|
||||
<dd>Learn about how to select hosts</dd>
|
||||
<dt><a class="reference external" href="https://github.com/ansible/ansible/tree/devel/examples/playbooks">Github examples directory</a></dt>
|
||||
<dd>Complete playbook files from the github project source</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>
|
||||
</dl>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
|
||||
<br/>
|
||||
</div>
|
||||
<footer class="footer">
|
||||
<div class="container">
|
||||
<p>
|
||||
<p>
|
||||
© Copyright 2012 Michael DeHaan.<br/>
|
||||
Last updated on Oct 08, 2012.<br/>
|
||||
</p>
|
||||
</div>
|
||||
</footer>
|
||||
</body>
|
||||
</html>
|
||||
@ -0,0 +1,95 @@
|
||||
YAML Syntax
|
||||
===========
|
||||
|
||||
This page provides a basic overview of correct YAML syntax, which is how Ansible
|
||||
playbooks (our configuration management language) are expressed.
|
||||
|
||||
We use YAML because it is easier to read and write for humans than other common
|
||||
data formats like XML or JSON. Further, there are libraries available for reading
|
||||
and writing YAML in most programming languages.
|
||||
|
||||
You may also wish to read :doc:`playbooks` at the same time to see how this
|
||||
is used in practice.
|
||||
|
||||
|
||||
YAML Basics
|
||||
-----------
|
||||
|
||||
For `ansible`, nearly every YAML file starts with a list.
|
||||
Each item in the list is a list of key/value pairs, commonly
|
||||
called a "hash" or a "dictionary". So, we need to know how
|
||||
to write lists and dictionaries in YAML.
|
||||
|
||||
There's another small quirk to YAML. All YAML files (regardless of their association with
|
||||
`ansible` or not) should start with ``---``. This is just a YAML
|
||||
format thing that means "this is the start of a document".
|
||||
|
||||
All members of a list are lines beginning at the same indentation level starting
|
||||
with a ``-`` (dash) character::
|
||||
|
||||
---
|
||||
# A list of tasty fruits
|
||||
- Apple
|
||||
- Orange
|
||||
- Strawberry
|
||||
- Mango
|
||||
|
||||
A dictionary is represented in a simple ``key:`` and ``value`` form::
|
||||
|
||||
---
|
||||
# An employee record
|
||||
name: John Eckersberg
|
||||
job: Developer
|
||||
skill: Elite
|
||||
|
||||
Dictionaries can also be represented in an abbreviated form if you really want to::
|
||||
|
||||
---
|
||||
# An employee record
|
||||
{name: John Eckersberg, job: Developer, skill: Elite}
|
||||
|
||||
.. _truthiness:
|
||||
|
||||
Ansible doesn't really use these too much, but you can also specify a
|
||||
boolean value (true/false) in several forms::
|
||||
|
||||
---
|
||||
knows_oop: True
|
||||
likes_emacs: TRUE
|
||||
uses_cvs: false
|
||||
|
||||
Let's combine what we learned so far in an arbitary YAML example. This really
|
||||
has nothing to do with Ansible, but will give you a feel for the format::
|
||||
|
||||
---
|
||||
# An employee record
|
||||
name: John Eckersberg
|
||||
job: Developer
|
||||
skill: Elite
|
||||
employed: True
|
||||
foods:
|
||||
- Apple
|
||||
- Orange
|
||||
- Strawberry
|
||||
- Mango
|
||||
languages:
|
||||
ruby: Elite
|
||||
python: Elite
|
||||
dotnet: Lame
|
||||
|
||||
That's all you really need to know about YAML to get started writing
|
||||
`Ansible` playbooks.
|
||||
|
||||
.. seealso::
|
||||
|
||||
:doc:`playbooks`
|
||||
Learn what playbooks can do and how to write/run them.
|
||||
`YAMLLint <http://yamllint.com/>`_
|
||||
YAML Lint (online) helps you debug YAML syntax if you are having problems
|
||||
`Github examples directory <https://github.com/ansible/ansible/tree/devel/examples/playbooks>`_
|
||||
Complete playbook files from the github project source
|
||||
`Mailing List <http://groups.google.com/group/ansible-project>`_
|
||||
Questions? Help? Ideas? Stop by the list on Google Groups
|
||||
`irc.freenode.net <http://irc.freenode.net>`_
|
||||
#ansible IRC chat channel
|
||||
|
||||
@ -0,0 +1,310 @@
|
||||
API & Integrations
|
||||
==================
|
||||
|
||||
There are several interesting ways to use Ansible from an API perspective. You can use
|
||||
the Ansible python API to control nodes, you can extend Ansible to respond to various python events,
|
||||
and you can plug in inventory data from external data sources. Ansible is written in its own
|
||||
API so you have a considerable amount of power across the board.
|
||||
|
||||
.. contents:: `Table of contents`
|
||||
:depth: 2
|
||||
:backlinks: top
|
||||
|
||||
Python API
|
||||
----------
|
||||
|
||||
The Python API is very powerful, and is how the ansible CLI and ansible-playbook
|
||||
are implemented.
|
||||
|
||||
It's pretty simple::
|
||||
|
||||
import ansible.runner
|
||||
|
||||
runner = ansible.runner.Runner(
|
||||
module_name='ping',
|
||||
module_args='',
|
||||
pattern='web*',
|
||||
forks=10
|
||||
)
|
||||
datastructure = runner.run()
|
||||
|
||||
The run method returns results per host, grouped by whether they
|
||||
could be contacted or not. Return types are module specific, as
|
||||
expressed in the 'ansible-modules' documentation.::
|
||||
|
||||
{
|
||||
"dark" : {
|
||||
"web1.example.com" : "failure message"
|
||||
}
|
||||
"contacted" : {
|
||||
"web2.example.com" : 1
|
||||
}
|
||||
}
|
||||
|
||||
A module can return any type of JSON data it wants, so Ansible can
|
||||
be used as a framework to rapidly build powerful applications and scripts.
|
||||
|
||||
Detailed API Example
|
||||
````````````````````
|
||||
|
||||
The following script prints out the uptime information for all hosts::
|
||||
|
||||
#!/usr/bin/python
|
||||
|
||||
import ansible.runner
|
||||
import sys
|
||||
|
||||
# construct the ansible runner and execute on all hosts
|
||||
results = ansible.runner.Runner(
|
||||
pattern='*', forks=10,
|
||||
module_name='command', module_args='/usr/bin/uptime',
|
||||
).run()
|
||||
|
||||
if results is None:
|
||||
print "No hosts found"
|
||||
sys.exit(1)
|
||||
|
||||
print "UP ***********"
|
||||
for (hostname, result) in results['contacted'].items():
|
||||
if not 'failed' in result:
|
||||
print "%s >>> %s" % (hostname, result['stdout'])
|
||||
|
||||
print "FAILED *******"
|
||||
for (hostname, result) in results['contacted'].items():
|
||||
if 'failed' in result:
|
||||
print "%s >>> %s" % (hostname, result['msg'])
|
||||
|
||||
print "DOWN *********"
|
||||
for (hostname, result) in results['dark'].items():
|
||||
print "%s >>> %s" % (hostname, result)
|
||||
|
||||
Advanced programmers may also wish to read the source to ansible itself, for
|
||||
it uses the Runner() API (with all available options) to implement the
|
||||
command line tools ``ansible`` and ``ansible-playbook``.
|
||||
|
||||
Plugins Repository
|
||||
------------------
|
||||
|
||||
The remainder of features in the API docs have components available in the `ansible-plugins <http://github.com/ansible/ansible-plugins>`_ repository. Please consult this repository for more information. Send us a github pull request if you develop any interesting features.
|
||||
|
||||
External Inventory Scripts
|
||||
--------------------------
|
||||
|
||||
Often a user of a configuration management system will want to keep inventory
|
||||
in a different system. Frequent examples include LDAP, `Cobbler <http://cobbler.github.com>`_,
|
||||
or a piece of expensive enterprisey CMDB software. Ansible easily supports all
|
||||
of these options via an external inventory system. The ansible-plugins repo contains some of these already -- including options for EC2/Eucalyptus and OpenStack, which will be detailed below.
|
||||
|
||||
It's possible to write an external inventory script in any language. 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.
|
||||
|
||||
Script Conventions
|
||||
``````````````````
|
||||
|
||||
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::
|
||||
|
||||
{
|
||||
'databases' : [ 'host1.example.com', 'host2.example.com' ],
|
||||
'webservers' : [ 'host2.example.com', 'host3.example.com' ],
|
||||
'atlanta' : [ 'host1.example.com', 'host4.example.com', 'host5.example.com' ]
|
||||
}
|
||||
|
||||
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 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::
|
||||
|
||||
{
|
||||
'favcolor' : 'red',
|
||||
'ntpserver' : 'wolf.example.com',
|
||||
'monitoring' : 'pack.example.com'
|
||||
}
|
||||
|
||||
Example: The Cobbler External Inventory Script
|
||||
``````````````````````````````````````````````
|
||||
|
||||
It is expected that many Ansible users will also be `Cobbler <http://cobbler.github.com>`_ users. Cobbler has a generic
|
||||
layer that allows it to represent data for multiple configuration management systems (even at the same time), and has
|
||||
been referred to as a 'lightweight CMDB' by some admins. This particular script will communicate with Cobbler
|
||||
using Cobbler's XMLRPC API.
|
||||
|
||||
To tie Ansible's inventory to Cobbler (optional), copy `this script <https://github.com/ansible/ansible-plugins/blob/master/inventory/cobbler.py>`_ to /etc/ansible/hosts and `chmod +x` the file. cobblerd will now need
|
||||
to be running when you are using Ansible.
|
||||
|
||||
Test the file by running `./etc/ansible/hosts` directly. You should see some JSON data output, but it may not have
|
||||
anything in it just yet.
|
||||
|
||||
Let's explore what this does. In cobbler, assume a scenario somewhat like the following::
|
||||
|
||||
cobbler profile add --name=webserver --distro=CentOS6-x86_64
|
||||
cobbler profile edit --name=webserver --mgmt-classes="webserver" --ksmeta="a=2 b=3"
|
||||
cobbler system edit --name=foo --dns-name="foo.example.com" --mgmt-classes="atlanta" --ksmeta="c=4"
|
||||
cobbler system edit --name=bar --dns-name="bar.example.com" --mgmt-classes="atlanta" --ksmeta="c=5"
|
||||
|
||||
In the example above, the system 'foo.example.com' will be addressable by ansible directly, but will also be addressable when using the group names 'webserver' or 'atlanta'. Since Ansible uses SSH, we'll try to contract system foo over 'foo.example.com', only, never just 'foo'. Similarly, if you try "ansible foo" it wouldn't find the system... but "ansible 'foo*'" would, because the system DNS name starts with 'foo'.
|
||||
|
||||
The script doesn't just provide host and group info. In addition, as a bonus, when the 'setup' module is run (which happens automatically when using playbooks), the variables 'a', 'b', and 'c' will all be auto-populated in the templates::
|
||||
|
||||
# file: /srv/motd.j2
|
||||
Welcome, I am templated with a value of a={{ a }}, b={{ b }}, and c={{ c }}
|
||||
|
||||
Which could be executed just like this::
|
||||
|
||||
ansible webserver -m setup
|
||||
ansible webserver -m template -a "src=/tmp/motd.j2 dest=/etc/motd"
|
||||
|
||||
.. note::
|
||||
The name 'webserver' came from cobbler, as did the variables for
|
||||
the config file. You can still pass in your own variables like
|
||||
normal in Ansible, but variables from the external inventory script
|
||||
will override any that have the same name.
|
||||
|
||||
So, with the template above (motd.j2), this would result in the following data being written to /etc/motd for system 'foo'::
|
||||
|
||||
Welcome, I am templated with a value of a=2, b=3, and c=4
|
||||
|
||||
And on system 'bar' (bar.example.com)::
|
||||
|
||||
Welcome, I am templated with a value of a=2, b=3, and c=5
|
||||
|
||||
And technically, though there is no major good reason to do it, this also works too::
|
||||
|
||||
ansible webserver -m shell -a "echo {{ a }}"
|
||||
|
||||
So in other words, you can use those variables in arguments/actions as well. You might use this to name
|
||||
a conf.d file appropriately or something similar. Who knows?
|
||||
|
||||
So that's the Cobbler integration support -- using the cobbler script as an example, it should be trivial to adapt Ansible to pull inventory, as well as variable information, from any data source. If you create anything interesting, please share with the mailing list, and we can keep it in the source code tree for others to use.
|
||||
|
||||
Example: AWS EC2 External Inventory Script
|
||||
``````````````````````````````````````````
|
||||
|
||||
If you use Amazon Web Services EC2, maintaining an inventory file might not be the best approach. For this reason, you can use the `EC2 external inventory <https://github.com/ansible/ansible-plugins/blob/master/inventory/ec2.py>`_ script.
|
||||
|
||||
You can use this script in one of two ways. The easiest is to use Ansible's ``-i`` command line option and specify the path to the script.
|
||||
|
||||
ansible -i ec2.py -u ubuntu us-east-1d -m ping
|
||||
|
||||
The second option is to copy the script to `/etc/ansible/hosts` and `chmod +x` it. You will also need to copy the ``ec2.ini`` file to `/etc/ansible/ec2.ini`. Then you can run ansible as you would normally.
|
||||
|
||||
To successfully make an API call to AWS, you will need to configure Boto (the Python interface to AWS). There are a `variety of methods <http://docs.pythonboto.org/en/latest/boto_config_tut.html>`_ available, but the simplest is just to export two environment variables:
|
||||
|
||||
export AWS_ACCESS_KEY_ID='AK123'
|
||||
export AWS_SECRET_ACCESS_KEY='abc123'
|
||||
|
||||
You can test the script by itself to make sure your config is correct
|
||||
|
||||
cd examples/scripts
|
||||
./ec2_external_inventory.py --list
|
||||
|
||||
After a few moments, you should see your entire EC2 inventory across all regions in JSON.
|
||||
|
||||
Since each region requires its own API call, if you are only using a small set of regions, feel free to edit ``ec2.ini`` and list only the regions you are interested in. There are other config options in ``ec2.ini`` including cache control, and destination variables.
|
||||
|
||||
At their heart, inventory files are simply a mapping from some name to a destination address. The default ``ec2.ini`` settings are configured for running Ansible from outside EC2 (from your laptop for example). If you are running Ansible from within EC2, internal DNS names and IP addresses may make more sense than public DNS names. In this case, you can modify the ``destination_variable`` in ``ec2.ini`` to be the private DNS name of an instance. This is particularly important when running Ansible within a private subnet inside a VPC, where the only way to access an instance is via its private IP address. For VPC instances, `vpc_destination_variable` in ``ec2.ini`` provides a means of using which ever `boto.ec2.instance variable <http://docs.pythonboto.org/en/latest/ref/ec2.html#module-boto.ec2.instance>`_ makes the most sense for your use case.
|
||||
|
||||
The EC2 external inventory provides mappings to instances from several groups:
|
||||
|
||||
Instance ID
|
||||
These are groups of one since instance IDs are unique.
|
||||
e.g.
|
||||
``i-00112233``
|
||||
``i-a1b1c1d1``
|
||||
|
||||
Region
|
||||
A group of all instances in an AWS region.
|
||||
e.g.
|
||||
``us-east-1``
|
||||
``us-west-2``
|
||||
|
||||
Availability Zone
|
||||
A group of all instances in an availability zone.
|
||||
e.g.
|
||||
``us-east-1a``
|
||||
``us-east-1b``
|
||||
|
||||
Security Group
|
||||
Instances belong to one or more security groups. A group is created for each security group, with all characters except alphanumerics, dashes (-) converted to underscores (_). Each group is prefixed by ``security_group_``
|
||||
e.g.
|
||||
``security_group_default``
|
||||
``security_group_webservers``
|
||||
``security_group_Pete_s_Fancy_Group``
|
||||
|
||||
Tags
|
||||
Each instance can have a variety of key/value pairs associated with it called Tags. The most common tag key is 'Name', though anything is possible. Each key/value pair is its own group of instances, again with special characters converted to underscores, in the format ``tag_KEY_VALUE``
|
||||
e.g.
|
||||
``tag_Name_Web``
|
||||
``tag_Name_redis-master-001``
|
||||
``tag_aws_cloudformation_logical-id_WebServerGroup``
|
||||
|
||||
When the Ansible is interacting with a specific server, the EC2 inventory script is called again with the ``--host HOST`` option. This looks up the HOST in the index cache to get the instance ID, and then makes an API call to AWS to get information about that specific instance. It then makes information about that instance available as variables to your playbooks. Each variable is prefixed by ``ec2_``. Here are some of the variables available:
|
||||
|
||||
- ec2_architecture
|
||||
- ec2_description
|
||||
- ec2_dns_name
|
||||
- ec2_id
|
||||
- ec2_image_id
|
||||
- ec2_instance_type
|
||||
- ec2_ip_address
|
||||
- ec2_kernel
|
||||
- ec2_key_name
|
||||
- ec2_launch_time
|
||||
- ec2_monitored
|
||||
- ec2_ownerId
|
||||
- ec2_placement
|
||||
- ec2_platform
|
||||
- ec2_previous_state
|
||||
- ec2_private_dns_name
|
||||
- ec2_private_ip_address
|
||||
- ec2_public_dns_name
|
||||
- ec2_ramdisk
|
||||
- ec2_region
|
||||
- ec2_root_device_name
|
||||
- ec2_root_device_type
|
||||
- ec2_security_group_ids
|
||||
- ec2_security_group_names
|
||||
- ec2_spot_instance_request_id
|
||||
- ec2_state
|
||||
- ec2_state_code
|
||||
- ec2_state_reason
|
||||
- ec2_status
|
||||
- ec2_subnet_id
|
||||
- ec2_tag_Name
|
||||
- ec2_tenancy
|
||||
- ec2_virtualization_type
|
||||
- ec2_vpc_id
|
||||
|
||||
Both ``ec2_security_group_ids`` and ``ec2_security_group_names`` are comma-separated lists of all security groups. Each EC2 tag is a variable in the format ``ec2_tag_KEY``.
|
||||
|
||||
To see the complete list of variables available for an instance, run the script by itself::
|
||||
|
||||
cd examples/scripts
|
||||
./ec2_external_inventory.py --host ec2-12-12-12-12.compute-1.amazonaws.com
|
||||
|
||||
Example: OpenStack
|
||||
``````````````````
|
||||
|
||||
Though not detailed here in as much depth as the EC2 module, there's also a OpenStack Nova external inventory source in the ansible-plugins repository. See the inline comments in the module source.
|
||||
|
||||
Callback Plugins
|
||||
----------------
|
||||
|
||||
Ansible can be configured via code to respond to external events. This can include enhancing logging, signalling an external software
|
||||
system, or even (yes, really) making sound effects. Some examples are contained in the ansible-plugins repository.
|
||||
|
||||
Connection Type Plugins
|
||||
-----------------------
|
||||
|
||||
By default, ansible ships with a 'paramiko' SSH, native ssh (just called 'ssh'), and 'local' connection type, which can be used
|
||||
in playbooks and with /usr/bin/ansible to decide how you want to talk to remote machines. The basics of these connection types
|
||||
are covered in the 'getting started' section. Should you want to extend Ansible to support other transports (SNMP? Message bus?
|
||||
Carrier Pigeon?) it's as simple as copying the format of one of the existing modules and dropping it into the connection plugins
|
||||
directory.
|
||||
|
||||
.. seealso::
|
||||
|
||||
:doc:`modules`
|
||||
List of built-in modules
|
||||
`Mailing List <http://groups.google.com/group/ansible-project>`_
|
||||
Questions? Help? Ideas? Stop by the list on Google Groups
|
||||
`irc.freenode.net <http://irc.freenode.net>`_
|
||||
#ansible IRC chat channel
|
||||
|
||||
@ -0,0 +1,143 @@
|
||||
Best Practices
|
||||
==============
|
||||
|
||||
Here are some tips for making the most of Ansible.
|
||||
|
||||
.. contents::
|
||||
:depth: 2
|
||||
:backlinks: top
|
||||
|
||||
Always Mention State
|
||||
++++++++++++++++++++
|
||||
|
||||
The 'state' parameter is optional to a lot of modules. Whether
|
||||
'state=present' or 'state=absent', it's always best to leave that
|
||||
parameter in your playbooks to make it clear, especially as some
|
||||
modules support additional states.
|
||||
|
||||
Group By Roles
|
||||
++++++++++++++
|
||||
|
||||
A system can be in multiple groups. See :doc:`patterns`. Having groups named after things like
|
||||
*webservers* and *dbservers* is repeated in the examples because it's a very powerful concept.
|
||||
|
||||
This allows playbooks to target machines based on role, as well as to assign role specific variables
|
||||
using the group variable system.
|
||||
|
||||
Directory Organization
|
||||
++++++++++++++++++++++
|
||||
|
||||
Playbooks should be organized like this::
|
||||
|
||||
# root of source control repository
|
||||
├── acme/
|
||||
│ ├── setup.yml
|
||||
│ └── stop.yml
|
||||
├── files/
|
||||
│ └── some_file_path_foo.conf
|
||||
├── handlers/
|
||||
│ └── main.yml
|
||||
├── tasks/
|
||||
│ ├── setup.yml
|
||||
│ └── stop.yml
|
||||
├── templates/
|
||||
│ ├── etc_acme_conf_acme.conf
|
||||
│ └── etc_other_conf_other.conf
|
||||
├── vars/
|
||||
│ └── main.yml
|
||||
└── global_vars.yml
|
||||
|
||||
Any directories or files not needed can be omitted. Not all modules
|
||||
may require 'vars' or 'files' sections, though most will require
|
||||
'handlers', 'tasks', and 'templates'. To review what each of
|
||||
these sections do, see :doc:`playbooks` and :doc:`playbooks2`.
|
||||
|
||||
The acme/setup.yml playbook would be as simple as::
|
||||
|
||||
---
|
||||
- hosts: webservers
|
||||
user: root
|
||||
|
||||
vars_files:
|
||||
- ../global_vars.yml
|
||||
- vars/main.yml
|
||||
tasks:
|
||||
- include: tasks/setup.yml
|
||||
handlers:
|
||||
- include: handlers/main.yml
|
||||
|
||||
The tasks are individually broken out in 'acme/tasks/setup.yml', and handlers, which are common to all task files,
|
||||
are contained in 'acme/handlers/main.yml'. As a reminder, handlers are mostly just used to notify services to restart
|
||||
when things change, and these are described in :doc:`playbooks`.
|
||||
|
||||
Including more than one setup file or more than one handlers file is of course legal.
|
||||
|
||||
Bundling Ansible Modules With Playbooks
|
||||
+++++++++++++++++++++++++++++++++++++++
|
||||
|
||||
.. versionadded:: 0.5
|
||||
|
||||
If a playbook has a "./library" directory relative to it's YAML file,
|
||||
this directory can be used to add ansible modules that will
|
||||
automatically be in the ansible module path. This is a great way to
|
||||
keep modules that go with a playbook together.
|
||||
|
||||
Miscellaneous Tips
|
||||
++++++++++++++++++
|
||||
|
||||
When you can do something simply, do something simply. Do not reach
|
||||
to use every feature of Ansible together, all at once. Use what works
|
||||
for you. For example, you should probably not need 'vars',
|
||||
'vars_files', 'vars_prompt' and '--extra-vars' all at once,
|
||||
while also using an external inventory file.
|
||||
|
||||
Optimize for readability. Whitespace between sections of YAML
|
||||
documents and in between tasks is strongly encouraged, as is usage of
|
||||
YAML comments, which start with '#'. It is also useful to comment
|
||||
at the top of each file the purpose of the individual file and the
|
||||
author, including email address.
|
||||
|
||||
It is possible to leave off the 'name' for a given task, though it
|
||||
is recommended to provide a descriptive comment about why something is
|
||||
being done instead.
|
||||
|
||||
Use version control. Keep your playbooks and inventory file in git
|
||||
(or another version control system), and commit when you make changes
|
||||
to them. This way you have an audit trail describing when and why you
|
||||
changed the rules automating your infrastructure.
|
||||
|
||||
Resist the urge to write the same playbooks and configuration files
|
||||
for heterogeneous distributions. While lots of software packages
|
||||
claim to make this easy on you, the configuration files are often
|
||||
quite different, to the point where it would be easier to treat them
|
||||
as different playbooks. This is why, for example, Ansible has a
|
||||
separate 'yum' and 'apt' module. Yum and apt have different
|
||||
capabilities, and we don't want to code for the least common
|
||||
denominator.
|
||||
|
||||
Use variables for user tunable settings versus having constants in the
|
||||
tasks file or templates, so that it is easy to reconfigure a playbook.
|
||||
Think about this as exposing the knobs to things you would like to
|
||||
tweak.
|
||||
|
||||
Since a system can be in more than one group, if you have multiple
|
||||
datacenters or sites, consider putting systems into groups by role,
|
||||
but also different groups by geography. This allows you to assign
|
||||
different variables to different geographies.
|
||||
|
||||
.. seealso::
|
||||
|
||||
:doc:`YAMLSyntax`
|
||||
Learn about YAML syntax
|
||||
:doc:`playbooks`
|
||||
Review the basic playbook features
|
||||
:doc:`modules`
|
||||
Learn about available modules
|
||||
:doc:`moduledev`
|
||||
Learn how to extend Ansible by writing your own modules
|
||||
:doc:`patterns`
|
||||
Learn about how to select hosts
|
||||
`Github examples directory <https://github.com/ansible/ansible/tree/devel/examples/playbooks>`_
|
||||
Complete playbook files from the github project source
|
||||
`Mailing List <http://groups.google.com/group/ansible-project>`_
|
||||
Questions? Help? Ideas? Stop by the list on Google Groups
|
||||
@ -0,0 +1,263 @@
|
||||
Command Line Examples And Next Steps
|
||||
====================================
|
||||
|
||||
.. highlight:: bash
|
||||
|
||||
The following examples show how to use `/usr/bin/ansible` for running
|
||||
ad hoc tasks. Start here.
|
||||
|
||||
For configuration management and deployments, you'll want to pick up on
|
||||
using `/usr/bin/ansible-playbook` -- the concepts port over directly.
|
||||
(See :doc:`playbooks` for more information about those)
|
||||
|
||||
.. contents::
|
||||
:depth: 2
|
||||
:backlinks: top
|
||||
|
||||
|
||||
Parallelism and Shell Commands
|
||||
``````````````````````````````
|
||||
|
||||
Let's use ansible's command line tool to reboot all web servers in Atlanta, 10 at a time. First, let's
|
||||
set up SSH-agent so it can remember our credentials::
|
||||
|
||||
$ ssh-agent bash
|
||||
$ ssh-add ~/.ssh/id_rsa.pub
|
||||
|
||||
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.
|
||||
|
||||
Now to run the command on all servers in a group, in this case,
|
||||
*atlanta*, in 10 parallel forks::
|
||||
|
||||
$ ansible atlanta -a "/sbin/reboot" -f 10
|
||||
|
||||
In 0.7 and later, this will default to running from your user account. If you do not like this
|
||||
behavior, pass in "-u username". (In 0.6 and before, it defaulted to root. Most folks prefered
|
||||
defaulting to the current user, so we changed it).
|
||||
|
||||
If you want to run commands as a different user, it looks like this::
|
||||
|
||||
$ ansible atlanta -a "/usr/bin/foo" -u username
|
||||
|
||||
If you want to run commands through sudo::
|
||||
|
||||
$ ansible atlanta -a "/usr/bin/foo" -u username --sudo [--ask-sudo-pass]
|
||||
|
||||
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.
|
||||
|
||||
It is also possible to sudo to a user other than root using
|
||||
``--sudo-user`` (``-U``)::
|
||||
|
||||
$ ansible atlanta -a "/usr/bin/foo" -u username -U otheruser [--ask-sudo-pass]
|
||||
|
||||
Ok, so those are basics. If you didn't read about patterns and groups yet, go back and read :doc:`patterns`.
|
||||
|
||||
The ``-f 10`` in the above specifies the usage of 10 simultaneous
|
||||
processes. Normally commands also take a ``-m`` for module name, but
|
||||
the default module name is 'command', so we didn't need to
|
||||
specify that all of the time. We'll use ``-m`` in later examples to
|
||||
run some other :doc:`modules`.
|
||||
|
||||
.. note::
|
||||
The :ref:`command` module requires absolute paths and does not
|
||||
support shell variables. If we want to execute a module using a
|
||||
shell, we can do those things, and also use pipe and redirection
|
||||
operators. Read more about the differences on the :doc:`modules`
|
||||
page.
|
||||
|
||||
Using the :ref:`shell` module looks like this::
|
||||
|
||||
$ ansible raleigh -m shell -a 'echo $TERM'
|
||||
|
||||
When running any command with the ansible *ad hoc* CLI (as opposed to
|
||||
:doc:`playbooks`), pay particular attention to shell quoting rules, so
|
||||
the shell doesn't eat a variable before it gets passed to Ansible.
|
||||
For example, using double vs single quotes in the above example would
|
||||
evaluate the variable on the box you were on.
|
||||
|
||||
So far we'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 'idempotence', and is a core design goal of ansible.
|
||||
However, we also recognize that running *ad hoc* commands is equally important, so Ansible easily supports both.
|
||||
|
||||
|
||||
File Transfer
|
||||
`````````````
|
||||
|
||||
Here's another use case for the `/usr/bin/ansible` command line. Ansible can SCP lots of files to multiple machines in parallel.
|
||||
|
||||
To transfer a file directly to many different servers::
|
||||
|
||||
$ ansible atlanta -m copy -a "src=/etc/hosts dest=/tmp/hosts"
|
||||
|
||||
If you use playbooks, you can also take advantage of the ``template`` module,
|
||||
which takes this another step further. (See module and playbook documentation).
|
||||
|
||||
The ``file`` module allows changing ownership and permissions on files. These
|
||||
same options can be passed directly to the ``copy`` module as well::
|
||||
|
||||
$ 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"
|
||||
|
||||
The ``file`` module can also create directories, similar to ``mkdir -p``::
|
||||
|
||||
$ ansible webservers -m file -a "dest=/path/to/c mode=644 owner=mdehaan group=mdehaan state=directory"
|
||||
|
||||
As well as delete directories (recursively) and delete files::
|
||||
|
||||
$ ansible webservers -m file -a "dest=/path/to/c state=absent"
|
||||
|
||||
|
||||
Managing Packages
|
||||
`````````````````
|
||||
|
||||
There are modules available for yum and apt. Here are some examples
|
||||
with yum.
|
||||
|
||||
Ensure a package is installed, but don't update it::
|
||||
|
||||
$ ansible webservers -m yum -a "pkg=acme state=installed"
|
||||
|
||||
Ensure a package is installed to a specific version::
|
||||
|
||||
$ ansible webservers -m yum -a "pkg=acme-1.5 state=installed"
|
||||
|
||||
Ensure a package is at the latest version::
|
||||
|
||||
$ ansible webservers -m yum -a "pkg=acme state=latest"
|
||||
|
||||
Ensure a package is not installed::
|
||||
|
||||
$ ansible webservers -m yum -a "pkg=acme state=removed"
|
||||
|
||||
Currently Ansible only has modules for managing packages with yum and apt. 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.
|
||||
|
||||
Users and Groups
|
||||
````````````````
|
||||
|
||||
The 'user' module allows easy creation and manipulation of
|
||||
existing user accounts, as well as removal of user accounts that may
|
||||
exist::
|
||||
|
||||
$ ansible all -m user -a "name=foo password=<crypted password here>"
|
||||
|
||||
$ ansible all -m user -a "name=foo state=absent"
|
||||
|
||||
See the :doc:`modules` section for details on all of the available options, including
|
||||
how to manipulate groups and group membership.
|
||||
|
||||
Deploying From Source Control
|
||||
`````````````````````````````
|
||||
|
||||
Deploy your webapp straight from git::
|
||||
|
||||
$ ansible webservers -m git -a "repo=git://foo.example.org/repo.git dest=/srv/myapp version=HEAD"
|
||||
|
||||
Since ansible modules can notify change handlers 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.
|
||||
|
||||
Managing Services
|
||||
`````````````````
|
||||
|
||||
Ensure a service is started on all webservers::
|
||||
|
||||
$ ansible webservers -m service -a "name=httpd state=started"
|
||||
|
||||
Alternatively, restart a service on all webservers::
|
||||
|
||||
$ ansible webservers -m service -a "name=httpd state=restarted"
|
||||
|
||||
Ensure a service is stopped::
|
||||
|
||||
$ ansible webservers -m service -a "name=httpd state=stopped"
|
||||
|
||||
Time Limited Background Operations
|
||||
``````````````````````````````````
|
||||
|
||||
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't lose track. If you kick hosts and don't want
|
||||
to poll, it looks like this::
|
||||
|
||||
$ ansible all -B 3600 -a "/usr/bin/long_running_operation --do-stuff"
|
||||
|
||||
If you do decide you want to check on the job status later, you can::
|
||||
|
||||
$ ansible all -m async_status -a "jid=123456789"
|
||||
|
||||
Polling is built-in and looks like this::
|
||||
|
||||
$ ansible all -B 1800 -P 60 -a "/usr/bin/long_running_operation --do-stuff"
|
||||
|
||||
The above example says "run for 30 minutes max (``-B``: 30*60=1800),
|
||||
poll for status (``-P``) every 60 seconds".
|
||||
|
||||
Poll mode is smart so all jobs will be started before polling will begin on any machine.
|
||||
Be sure to use a high enough ``--forks`` value if you want to get all of your jobs started
|
||||
very quickly. After the time limit (in seconds) runs out (``-B``), the process on
|
||||
the remote nodes will be terminated.
|
||||
|
||||
Typically you'll be only be backgrounding long-running
|
||||
shell commands or software upgrades only. Backgrounding the copy module does not do a background file transfer. :doc:`playbooks` also support polling, and have a simplified syntax for this.
|
||||
|
||||
Limiting Selected Hosts
|
||||
```````````````````````
|
||||
|
||||
.. versionadded:: 0.7
|
||||
|
||||
What hosts you select to manage can be additionally constrained by using the '--limit' parameter or
|
||||
by using 'batch' (or 'range') selectors.
|
||||
|
||||
As mentioned above, patterns can be strung together to select hosts in more than one group::
|
||||
|
||||
$ ansible webservers:dbservers -m command -a "/bin/foo xyz"
|
||||
|
||||
This is an "or" condition. If you want to further constrain the selection, use --limit, which
|
||||
also works with ``ansible-playbook``::
|
||||
|
||||
$ ansible webservers:dbservers -m command -a "/bin/foo xyz" region
|
||||
|
||||
Now let's talk about range selection. Suppose you have 1000 servers in group 'datacenter', but only want to target one at a time. This is also easy::
|
||||
|
||||
$ ansible webservers[0-99] -m command -a "/bin/foo xyz"
|
||||
$ ansible webservers[100-199] -m command -a "/bin/foo xyz"
|
||||
|
||||
This will select the first 100, then the second 100, host entries in the webservers group. (It does not matter
|
||||
what their names or IP addresses are).
|
||||
|
||||
Both of these methods can be used at the same time, and ranges can also be passed to the --limit parameter.
|
||||
|
||||
Configuration & Defaults
|
||||
````````````````````````
|
||||
|
||||
.. versionadded:: 0.7
|
||||
|
||||
Ansible has an optional configuration file that can be used to tune settings and also eliminate the need to pass various command line flags. Ansible will look for the config file in the following order, using
|
||||
the first config file it finds present:
|
||||
|
||||
1. File specified by the ``ANSIBLE_CONFIG`` environment variable
|
||||
2. ``ansible.cfg`` in the current working directory. (version 0.8 and up)
|
||||
3. ``~/.ansible.cfg``
|
||||
4. ``/etc/ansible/ansible.cfg``
|
||||
|
||||
For those running from source, a sample configuration file lives in the examples/ directory. The RPM will install configuration into /etc/ansible/ansible.cfg automatically.
|
||||
|
||||
.. seealso::
|
||||
|
||||
:doc:`modules`
|
||||
A list of available modules
|
||||
:doc:`playbooks`
|
||||
Using ansible for configuration management & deployment
|
||||
`Mailing List <http://groups.google.com/group/ansible-project>`_
|
||||
Questions? Help? Ideas? Stop by the list on Google Groups
|
||||
`irc.freenode.net <http://irc.freenode.net>`_
|
||||
#ansible IRC chat channel
|
||||
@ -0,0 +1,247 @@
|
||||
Getting Started
|
||||
===============
|
||||
|
||||
.. contents::
|
||||
:depth: 2
|
||||
:backlinks: top
|
||||
|
||||
Requirements
|
||||
````````````
|
||||
|
||||
Requirements for Ansible are extremely minimal.
|
||||
|
||||
Ansible is written for Python 2.6. If you are running Python 2.5 on an "Enterprise Linux" variant,
|
||||
your distribution can easily install 2.6 (see instructions in the next section). Newer versions
|
||||
of Linux and OS X should already have 2.6.
|
||||
|
||||
In additon to Python 2.6, you will want the following packages:
|
||||
|
||||
* ``paramiko``
|
||||
* ``PyYAML``
|
||||
* ``python-jinja2``
|
||||
|
||||
On the managed nodes, you only need Python 2.4 or later, but if you are are running less than Python 2.6 on them, you will
|
||||
also need:
|
||||
|
||||
* ``python-simplejson``
|
||||
|
||||
.. note::
|
||||
|
||||
Ansible's "raw" module (for executing commands in a quick and dirty
|
||||
way) and the copy module -- some of the most basic features in
|
||||
ansible -- don't even need that. So technically, you can use
|
||||
Ansible to install python-simplejson using the raw module, which
|
||||
then allows you to use everything else. (That's jumping ahead
|
||||
though.)
|
||||
|
||||
Python 2.6 EPEL instructions for RHEL and CentOS 5
|
||||
``````````````````````````````````````````````````
|
||||
|
||||
These distributions don't have Python 2.6 by default, but it is easily
|
||||
installable. If you have not already done so, `configure EPEL
|
||||
<http://fedoraproject.org/wiki/EPEL>`_
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ yum install python26 python26-PyYAML python26-paramiko python26-jinja2
|
||||
|
||||
Getting Ansible
|
||||
```````````````
|
||||
|
||||
If you are interested in using all the latest features, you may wish to keep up to date
|
||||
with the development branch of the git checkout. This also makes it easiest to contribute
|
||||
back to the project.
|
||||
|
||||
Instructions for installing from source are below.
|
||||
|
||||
Ansible's release cycles are about one month long. Due to this
|
||||
short release cycle, any bugs will generally be fixed in the next release versus maintaining
|
||||
backports on the stable branch.
|
||||
|
||||
You may also wish to follow the `Github project <https://github.com/ansible/ansible>`_ if
|
||||
you have a github account. This is also where we keep the issue tracker for sharing
|
||||
bugs and feature ideas.
|
||||
|
||||
|
||||
Running From Checkout
|
||||
+++++++++++++++++++++
|
||||
|
||||
Ansible is trivially easy to run from a checkout, root permissions are not required
|
||||
to use it:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ git clone git://github.com/ansible/ansible.git
|
||||
$ cd ./ansible
|
||||
$ source ./hacking/env-setup
|
||||
|
||||
You can optionally specify an inventory file (see :doc:`patterns`) other than /etc/ansible/hosts:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ echo "127.0.0.1" > ~/ansible_hosts
|
||||
$ export ANSIBLE_HOSTS=~/ansible_hosts
|
||||
|
||||
Now let's test things:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ ansible all -m ping --ask-pass
|
||||
|
||||
|
||||
Make Install
|
||||
++++++++++++
|
||||
|
||||
If you are not working from a distribution where Ansible is packaged yet, you can install Ansible
|
||||
using "make install". This is done through `python-distutils`:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ git clone git://github.com/ansible/ansible.git
|
||||
$ cd ./ansible
|
||||
$ sudo make install
|
||||
|
||||
|
||||
Via RPM
|
||||
+++++++
|
||||
|
||||
RPMs for the last Ansible release are available for `EPEL
|
||||
<http://fedoraproject.org/wiki/EPEL>`_ 6 and currently supported
|
||||
Fedora distributions. Ansible itself can manage earlier operating
|
||||
systems that contain python 2.4 or higher.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
# install the epel-release RPM if needed on CentOS, RHEL, or Scientific Linux
|
||||
$ sudo yum install ansible
|
||||
|
||||
You can also use the ``make rpm`` command to build an RPM you can
|
||||
distribute and install:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ git clone git://github.com/ansible/ansible.git
|
||||
$ cd ./ansible
|
||||
$ make rpm
|
||||
$ sudo rpm -Uvh ~/rpmbuild/ansible-*.noarch.rpm
|
||||
|
||||
Debian, Gentoo, Arch, Others
|
||||
++++++++++++++++++++++++++++
|
||||
|
||||
Ubuntu builds are available `in a PPA here <https://launchpad.net/~rquillo/+archive/ansible>`_
|
||||
|
||||
Debian/Ubuntu package recipes can also be built from the source checkout, run:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ make debian
|
||||
|
||||
Gentoo eBuilds are available `on github here <https://github.com/uu/ubuilds>`_
|
||||
|
||||
An Arch PKGBUILD is available on `AUR <https://aur.archlinux.org/packages.php?ID=58621>`_
|
||||
If you have python3 installed on Arch, you probably want to symlink python to python2:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ sudo ln -sf /usr/bin/python2 /usr/bin/python
|
||||
|
||||
If you would like to package Ansible for Homebrew, BSD, or others,
|
||||
please stop by the mailing list and say hi!
|
||||
|
||||
|
||||
Tagged Releases
|
||||
+++++++++++++++
|
||||
|
||||
Tagged releases are available as tar.gz files from the Ansible github
|
||||
project page:
|
||||
|
||||
* `Ansible/downloads <https://github.com/ansible/ansible/downloads>`_
|
||||
|
||||
Choosing Between Paramiko and Native SSH
|
||||
````````````````````````````````````````
|
||||
|
||||
By default, ansible uses paramiko to talk to managed nodes over SSH. Paramiko is fast, works
|
||||
very transparently, requires no configuration, and is a good choice for most users.
|
||||
However, it does not support some advanced SSH features that folks will want to use.
|
||||
|
||||
.. versionadded:: 0.5
|
||||
|
||||
If you want to leverage more advanced SSH features (such as Kerberized
|
||||
SSH or jump hosts), pass the flag "--connection=ssh" to any ansible
|
||||
command, or set the ANSIBLE_TRANSPORT environment variable to
|
||||
'ssh'. This will cause Ansible to use openssh tools instead.
|
||||
|
||||
If ANSIBLE_SSH_ARGS are not set, ansible will try to use some sensible ControlMaster options
|
||||
by default. You are free to override this environment variable, but should still pass ControlMaster
|
||||
options to ensure performance of this transport. With ControlMaster in use, both transports
|
||||
are roughly the same speed. Without CM, the binary ssh transport is signficantly slower.
|
||||
|
||||
If none of this makes sense to you, the default paramiko option is probably fine.
|
||||
|
||||
Your first commands
|
||||
```````````````````
|
||||
|
||||
Now that you've installed Ansible, it's time to test it.
|
||||
|
||||
Edit (or create) /etc/ansible/hosts and put one or more remote systems in it, for
|
||||
which you have your SSH key in ``authorized_keys``::
|
||||
|
||||
192.168.1.50
|
||||
aserver.example.org
|
||||
bserver.example.org
|
||||
|
||||
Set up SSH agent to avoid retyping passwords:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ ssh-agent bash
|
||||
$ ssh-add ~/.ssh/id_rsa
|
||||
|
||||
(Depending on your setup, you may wish to ansible's --private-key-file option to specify a pem file instead)
|
||||
|
||||
Now ping all your nodes:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ ansible all -m ping
|
||||
|
||||
In Ansible 0.7 and later, ansible will attempt to remote connect to the machines using your current
|
||||
user name, just like SSH would. In 0.6 and before, this actually defaults to 'root' (we liked the current
|
||||
user behavior better). To override the remote user name, just use the '-u' parameter.
|
||||
|
||||
If you would like to access sudo mode, there are also flags to do that:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
# as bruce
|
||||
$ ansible all -m ping -u bruce
|
||||
# as bruce, sudoing to root
|
||||
$ ansible all -m ping -u bruce --sudo
|
||||
# as bruce, sudoing to batman
|
||||
$ ansible all -m ping -u bruce --sudo --sudo-user batman
|
||||
|
||||
Now run a live command on all of your nodes:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$ ansible all -a "/bin/echo hello"
|
||||
|
||||
Congratulations. You've just contacted your nodes with Ansible. It's
|
||||
now time to read some of the more real-world :doc:`examples`, and explore
|
||||
what you can do with different modules, as well as the Ansible
|
||||
:doc:`playbooks` language. Ansible is not just about running commands, it
|
||||
also has powerful configuration management and deployment features. There's more to
|
||||
explore, but you already have a fully working infrastructure!
|
||||
|
||||
|
||||
.. seealso::
|
||||
|
||||
:doc:`examples`
|
||||
Examples of basic commands
|
||||
:doc:`playbooks`
|
||||
Learning ansible's configuration management language
|
||||
`Mailing List <http://groups.google.com/group/ansible-project>`_
|
||||
Questions? Help? Ideas? Stop by the list on Google Groups
|
||||
`irc.freenode.net <http://irc.freenode.net>`_
|
||||
#ansible IRC chat channel
|
||||
|
||||
@ -0,0 +1,18 @@
|
||||
|
||||
Contents
|
||||
````````
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
gettingstarted
|
||||
patterns
|
||||
examples
|
||||
modules
|
||||
YAMLSyntax
|
||||
playbooks
|
||||
playbooks2
|
||||
bestpractices
|
||||
api
|
||||
moduledev
|
||||
|
||||
@ -0,0 +1,346 @@
|
||||
Module Development
|
||||
==================
|
||||
|
||||
Ansible modules are reusable units of magic that can be used by the Ansible API,
|
||||
or by the `ansible` or `ansible-playbook` programs.
|
||||
|
||||
Modules can be written in any language and are found in the path specified
|
||||
by `ANSIBLE_LIBRARY_PATH` or the ``--module-path`` command line option.
|
||||
|
||||
.. contents::
|
||||
:depth: 2
|
||||
:backlinks: top
|
||||
|
||||
|
||||
Tutorial
|
||||
````````
|
||||
Let's build a module to get and set the system time. For starters, let's build
|
||||
a module that just outputs the current time.
|
||||
|
||||
We are going to use Python here but any language is possible. Only File I/O and outputing to standard
|
||||
out are required. So, bash, C++, clojure, Python, Ruby, whatever you want
|
||||
is fine.
|
||||
|
||||
Now Python Ansible modules contain some extremely powerful shortcuts (that all the core modules use)
|
||||
but first we are going to build a module the very hard way. The reason we do this is because modules
|
||||
written in any language OTHER than Python are going to have to do exactly this. We'll show the easy
|
||||
way later.
|
||||
|
||||
So, here's an example. You would never really need to build a module to set the system time,
|
||||
the 'command' module could already be used to do this. Though we're going to make one.
|
||||
|
||||
Reading the modules that come with ansible (linked above) is a great way to learn how to write
|
||||
modules. Keep in mind, though, that some modules in ansible's source tree are internalisms,
|
||||
so look at `service` or `yum`, and don't stare too close into things like `async_wrapper` or
|
||||
you'll turn to stone. Nobody ever executes async_wrapper directly.
|
||||
|
||||
Ok, let's get going with an example. We'll use Python. For starters, save this as a file named `time`::
|
||||
|
||||
#!/usr/bin/python
|
||||
|
||||
import datetime
|
||||
import json
|
||||
|
||||
date = str(datetime.datetime.now())
|
||||
print json.dumps({
|
||||
"time" : date
|
||||
})
|
||||
|
||||
Testing Modules
|
||||
```````````````
|
||||
|
||||
There's a useful test script in the source checkout for ansible::
|
||||
|
||||
git clone git@github.com:ansible/ansible.git
|
||||
chmod +x ansible/hacking/test-module
|
||||
|
||||
Let's run the script you just wrote with that::
|
||||
|
||||
ansible/hacking/test-module -m ./time
|
||||
|
||||
You should see output that looks something like this::
|
||||
|
||||
{u'time': u'2012-03-14 22:13:48.539183'}
|
||||
|
||||
If you did not, you might have a typo in your module, so recheck it and try again.
|
||||
|
||||
Reading Input
|
||||
`````````````
|
||||
|
||||
Let's modify the module to allow setting the current time. We'll do this by seeing
|
||||
if a key value pair in the form `time=<string>` is passed in to the module.
|
||||
|
||||
Ansible internally saves arguments to an arguments file. So we must read the file
|
||||
and parse it. The arguments file is just a string, so any form of arguments are legal.
|
||||
Here we'll do some basic parsing to treat the input as key=value.
|
||||
|
||||
The example usage we are trying to achieve to set the time is::
|
||||
|
||||
time time="March 14 22:10"
|
||||
|
||||
If no time parameter is set, we'll just leave the time as is and return the current time.
|
||||
|
||||
.. note:
|
||||
This is obviously an unrealistic idea for a module. You'd most likely just
|
||||
use the shell module. However, it probably makes a decent tutorial.
|
||||
|
||||
Let's look at the code. Read the comments as we'll explain as we go. Note that this
|
||||
is highly verbose because it's intended as an educational example. You can write modules
|
||||
a lot shorter than this::
|
||||
|
||||
#!/usr/bin/python
|
||||
|
||||
# import some python modules that we'll use. These are all
|
||||
# available in Python's core
|
||||
|
||||
import datetime
|
||||
import sys
|
||||
import json
|
||||
import os
|
||||
import shlex
|
||||
|
||||
# read the argument string from the arguments file
|
||||
args_file = sys.argv[1]
|
||||
args_data = file(args_file).read()
|
||||
|
||||
# for this module, we're going to do key=value style arguments
|
||||
# this is up to each module to decide what it wants, but all
|
||||
# core modules besides 'command' and 'shell' take key=value
|
||||
# so this is highly recommended
|
||||
|
||||
arguments = shlex.split(args_data)
|
||||
for arg in arguments:
|
||||
|
||||
# ignore any arguments without an equals in it
|
||||
if arg.find("=") != -1:
|
||||
|
||||
(key, value) = arg.split("=")
|
||||
|
||||
# if setting the time, the key 'time'
|
||||
# will contain the value we want to set the time to
|
||||
|
||||
if key == "time":
|
||||
|
||||
# now we'll affect the change. Many modules
|
||||
# will strive to be 'idempotent', meaning they
|
||||
# will only make changes when the desired state
|
||||
# expressed to the module does not match
|
||||
# the current state. Look at 'service'
|
||||
# or 'yum' in the main git tree for an example
|
||||
# of how that might look.
|
||||
|
||||
rc = os.system("date -s \"%s\"" % value)
|
||||
|
||||
# always handle all possible errors
|
||||
#
|
||||
# when returning a failure, include 'failed'
|
||||
# in the return data, and explain the failure
|
||||
# in 'msg'. Both of these conventions are
|
||||
# required however additional keys and values
|
||||
# can be added.
|
||||
|
||||
if rc != 0:
|
||||
print json.dumps({
|
||||
"failed" : True,
|
||||
"msg" : "failed setting the time"
|
||||
})
|
||||
sys.exit(1)
|
||||
|
||||
# when things do not fail, we do not
|
||||
# have any restrictions on what kinds of
|
||||
# data are returned, but it's always a
|
||||
# good idea to include whether or not
|
||||
# a change was made, as that will allow
|
||||
# notifiers to be used in playbooks.
|
||||
|
||||
date = str(datetime.datetime.now())
|
||||
print json.dumps({
|
||||
"time" : date,
|
||||
"changed" : True
|
||||
})
|
||||
sys.exit(0)
|
||||
|
||||
# if no parameters are sent, the module may or
|
||||
# may not error out, this one will just
|
||||
# return the time
|
||||
|
||||
date = str(datetime.datetime.now())
|
||||
print json.dumps({
|
||||
"time" : date
|
||||
})
|
||||
|
||||
Let's test that module::
|
||||
|
||||
ansible/hacking/test-module -m ./time -a time=\"March 14 12:23\"
|
||||
|
||||
This should return something like::
|
||||
|
||||
{"changed": True, "time": "2012-03-14 12:23:00.000307"}
|
||||
|
||||
Module Provided 'Facts'
|
||||
```````````````````````
|
||||
|
||||
The 'setup' module that ships with Ansible provides many variables about a system that can be used in playbooks
|
||||
and templates. However, it's possible to also add your own facts without modifying the system module. To do
|
||||
this, just have the module return a `ansible_facts` key, like so, along with other return data::
|
||||
|
||||
{
|
||||
"changed" : True,
|
||||
"rc" : 5,
|
||||
"ansible_facts" : {
|
||||
"leptons" : 5000
|
||||
"colors" : {
|
||||
"red" : "FF0000",
|
||||
"white" : "FFFFFF"
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
These 'facts' will be available to all statements called after that module (but not before) in the playbook.
|
||||
A good idea might be make a module called 'site_facts' and always call it at the top of each playbook, though
|
||||
we're always open to improving the selection of core facts in Ansible as well.
|
||||
|
||||
Common Module Boilerplate
|
||||
`````````````````````````
|
||||
|
||||
As mentioned, if you are writing a module in Python, there are some very powerful shortcuts you can use.
|
||||
Modules are still transferred as one file, but an arguments file is no longer needed, so these are not
|
||||
only shorter in terms of code, they are actually FASTER in terms of execution time.
|
||||
|
||||
Rather than mention these here, the best way to learn is to read some of the `source of the modules <https://github.com/ansible/ansible/tree/devel/library>`_ that come with Ansible.
|
||||
|
||||
The 'group' and 'user' modules are reasonably non-trival and showcase what this looks like.
|
||||
|
||||
Key parts include always ending the module file with::
|
||||
|
||||
# include magic from lib/ansible/module_common.py
|
||||
#<<INCLUDE_ANSIBLE_MODULE_COMMON>>
|
||||
main()
|
||||
|
||||
And instantiating the module class like::
|
||||
|
||||
module = AnsibleModule(
|
||||
argument_spec = dict(
|
||||
state = dict(default='present', choices=['present', 'absent']),
|
||||
name = dict(required=True),
|
||||
enabled = dict(required=True, choices=BOOLEANS),
|
||||
something = dict(aliases=['whatever'])
|
||||
)
|
||||
)
|
||||
|
||||
The AnsibleModule provides lots of common code for handling returns, parses your arguments
|
||||
for you, and allows you to check inputs.
|
||||
|
||||
Successful returns are made like this::
|
||||
|
||||
module.exit_json(changed=True, something_else=12345)
|
||||
|
||||
And failures are just as simple (where 'msg' is a required parameter to explain the error)::
|
||||
|
||||
module.fail_json(msg="Something fatal happened")
|
||||
|
||||
There are also other useful functions in the module class, such as module.md5(path). See
|
||||
lib/ansible/module_common.py in the source checkout for implementation details.
|
||||
|
||||
Again, modules developed this way are best tested with the hacking/test-module script in the git
|
||||
source checkout. Because of the magic involved, this is really the only way the scripts
|
||||
can function outside of Ansible.
|
||||
|
||||
If submitting a module to ansible's core code, which we encourage, use of the AnsibleModule
|
||||
class is required.
|
||||
|
||||
Common Pitfalls
|
||||
```````````````
|
||||
|
||||
You should also never do this in a module::
|
||||
|
||||
print "some status message"
|
||||
|
||||
Because the output is supposed to be valid JSON. Except that's not quite true,
|
||||
but we'll get to that later.
|
||||
|
||||
Modules must not output anything on standard error, because the system will merge
|
||||
standard out with standard error and prevent the JSON from parsing. Capturing standard
|
||||
error and returning it as a variable in the JSON on standard out is fine, and is, in fact,
|
||||
how the command module is implemented.
|
||||
|
||||
If a module returns stderr or otherwise fails to produce valid JSON, the actual output
|
||||
will still be shown in Ansible, but the command will not succeed.
|
||||
|
||||
Always use the hacking/test-module script when developing modules and it will warn
|
||||
you about these kind of things.
|
||||
|
||||
Conventions/Recomendations
|
||||
``````````````````````````
|
||||
|
||||
As a reminder from the example code above, here are some basic conventions
|
||||
and guidelines:
|
||||
|
||||
* If the module is addressing an object, the parameter for that object should be called 'name' whenever possible, or accept 'name' as an alias.
|
||||
|
||||
* If you have a company module that returns facts specific to your installations, a good name for this module is `site_facts`.
|
||||
|
||||
* Modules accepting boolean status should generally accept 'yes', 'no', 'true', 'false', or anything else a user may likely throw at them. The AnsibleModule common code supports this with "choices=BOOLEANS" and a module.boolean(value) casting function.
|
||||
|
||||
* Include a minimum of dependencies if possible. If there are dependencies, document them at the top of the module file, and have the module raise JSON error messages when the import fails.
|
||||
|
||||
* Modules must be self contained in one file to be auto-transferred by ansible.
|
||||
|
||||
* If packaging modules in an RPM, they only need to be installed on the control machine and should be dropped into /usr/share/ansible. This is entirely optional and up to you.
|
||||
|
||||
* Modules should return JSON or key=value results all on one line. JSON is best if you can do JSON. All return types must be hashes (dictionaries) although they can be nested. Lists or simple scalar values are not supported, though they can be trivially contained inside a dictionary.
|
||||
|
||||
* In the event of failure, a key of 'failed' should be included, along with a string explanation in 'msg'. Modules that raise tracebacks (stacktraces) are generally considered 'poor' modules, though Ansible can deal with these returns and will automatically convert anything unparseable into a failed result. If you are using the AnsibleModule common Python code, the 'failed' element will be included for you automatically when you call 'fail_json'.
|
||||
|
||||
* Return codes from modules are not actually not signficant, but continue on with 0=success and non-zero=failure for reasons of future proofing.
|
||||
|
||||
* As results from many hosts will be aggregrated at once, modules should return only relevant output. Returning the entire contents of a log file is generally bad form.
|
||||
|
||||
Shorthand Vs JSON
|
||||
`````````````````
|
||||
|
||||
To make it easier to write modules in bash and in cases where a JSON
|
||||
module might not be available, it is acceptable for a module to return
|
||||
key=value output all on one line, like this. The Ansible parser
|
||||
will know what to do::
|
||||
|
||||
somekey=1 somevalue=2 rc=3 favcolor=red
|
||||
|
||||
If you're writing a module in Python or Ruby or whatever, though, returning
|
||||
JSON is probably the simplest way to go.
|
||||
|
||||
|
||||
Sharing Your Module
|
||||
```````````````````
|
||||
|
||||
If you think your module is generally useful to others, a good place to share it
|
||||
is in `Ansible Resources <https://github.com/ansible/ansible-resources>`_. This is maintained
|
||||
as a simple repo with pointers to other github projects.
|
||||
|
||||
Contrib modules here can be implemented in a variety of languages.
|
||||
We would like to build up as many of these as possible in as many languages as possible.
|
||||
|
||||
`Ansible Mailing List <http://groups.google.com/group/ansible-project>`_
|
||||
|
||||
Getting Your Module Into Core
|
||||
`````````````````````````````
|
||||
|
||||
High-quality modules with minimal dependencies
|
||||
can be included in the core, but core modules (just due to the programming
|
||||
preferences of the developers) will need to be implemented in Python and use
|
||||
the AnsibleModule common code, and should generally use consistent arguments with the rest of
|
||||
the program. Stop by the mailing list to inquire about requirements.
|
||||
|
||||
.. seealso::
|
||||
|
||||
:doc:`modules`
|
||||
Learn about available modules
|
||||
`Ansible Resources <https://github.com/ansible/ansible-resources>`_
|
||||
User contributed playbooks, modules, and articles
|
||||
`Github modules directory <https://github.com/ansible/ansible/tree/devel/library>`_
|
||||
Browse source of core modules
|
||||
`Mailing List <http://groups.google.com/group/ansible-project>`_
|
||||
Questions? Help? Ideas? Stop by the list on Google Groups
|
||||
`irc.freenode.net <http://irc.freenode.net>`_
|
||||
#ansible IRC chat channel
|
||||
|
||||
@ -0,0 +1,74 @@
|
||||
Ansible Modules
|
||||
===============
|
||||
|
||||
.. contents::
|
||||
:depth: 2
|
||||
:backlinks: top
|
||||
|
||||
Introduction
|
||||
````````````
|
||||
|
||||
|
||||
Ansible ships with a number of modules (called the 'module library')
|
||||
that can be executed directly on remote hosts or through :doc:`playbooks`.
|
||||
Users can also write their own modules. These modules can control system
|
||||
resources, like services, packages, or files (anything really), or
|
||||
handle executing system commands.
|
||||
|
||||
Let's review how we execute three different modules from the command line::
|
||||
|
||||
ansible webservers -m service -a "name=httpd state=running"
|
||||
ansible webservers -m ping
|
||||
ansible webservers -m command -a "/sbin/reboot -t now"
|
||||
|
||||
Each module supports taking arguments. Nearly all modules take ``key=value``
|
||||
arguments, space delimited. Some modules take no arguments, and the
|
||||
command/shell modules simply take the string of the command you want to run.
|
||||
|
||||
From playbooks, Ansible modules are executed in a very similar way::
|
||||
|
||||
- name: reboot the servers
|
||||
action: command /sbin/reboot -t now
|
||||
|
||||
All modules technically return JSON format data, though if you are using the
|
||||
command line or playbooks, you don't really need to know much about
|
||||
that. If you're writing your own module, you care, and this means you do
|
||||
not have to write modules in any particular language -- you get to choose.
|
||||
|
||||
Modules are `idempotent`, meaning they will seek to avoid changes to the system unless a change needs to be made. When using Ansible
|
||||
playbooks, these modules can trigger 'change events' in the form of notifying 'handlers'
|
||||
to run additional tasks.
|
||||
|
||||
Let's see what's available in the Ansible module library, out of the box:
|
||||
|
||||
|
||||
.. include:: modules/_list.rst
|
||||
|
||||
|
||||
Additional Contrib Modules
|
||||
``````````````````````````
|
||||
|
||||
In addition to the following built-in modules, community modules are available at `Ansible Resources <http://github.com/ansible/ansible-resources>`_.
|
||||
|
||||
Writing your own modules
|
||||
````````````````````````
|
||||
|
||||
See :doc:`moduledev`.
|
||||
|
||||
.. seealso::
|
||||
|
||||
`Ansible Resources (Contrib) <https://github.com/ansible/ansible-resources>`_
|
||||
User contributed playbooks, modules, and articles
|
||||
:doc:`examples`
|
||||
Examples of using modules in /usr/bin/ansible
|
||||
:doc:`playbooks`
|
||||
Examples of using modules with /usr/bin/ansible-playbook
|
||||
:doc:`moduledev`
|
||||
How to write your own modules
|
||||
:doc:`api`
|
||||
Examples of using modules with the Python API
|
||||
`Mailing List <http://groups.google.com/group/ansible-project>`_
|
||||
Questions? Help? Ideas? Stop by the list on Google Groups
|
||||
`irc.freenode.net <http://irc.freenode.net>`_
|
||||
#ansible IRC chat channel
|
||||
|
||||
@ -0,0 +1,43 @@
|
||||
.. Generated by module_formatter
|
||||
.. include:: modules/apt.rst
|
||||
.. include:: modules/apt_repository.rst
|
||||
.. include:: modules/assemble.rst
|
||||
.. include:: modules/async_status.rst
|
||||
.. include:: modules/authorized_key.rst
|
||||
.. include:: modules/command.rst
|
||||
.. include:: modules/copy.rst
|
||||
.. include:: modules/easy_install.rst
|
||||
.. include:: modules/facter.rst
|
||||
.. include:: modules/fail.rst
|
||||
.. include:: modules/fetch.rst
|
||||
.. include:: modules/file.rst
|
||||
.. include:: modules/fireball.rst
|
||||
.. include:: modules/get_url.rst
|
||||
.. include:: modules/git.rst
|
||||
.. include:: modules/group.rst
|
||||
.. include:: modules/ini_file.rst
|
||||
.. include:: modules/lineinfile.rst
|
||||
.. include:: modules/mount.rst
|
||||
.. include:: modules/mysql_db.rst
|
||||
.. include:: modules/mysql_user.rst
|
||||
.. include:: modules/nagios.rst
|
||||
.. include:: modules/ohai.rst
|
||||
.. include:: modules/pause.rst
|
||||
.. include:: modules/ping.rst
|
||||
.. include:: modules/pip.rst
|
||||
.. include:: modules/postgresql_db.rst
|
||||
.. include:: modules/postgresql_user.rst
|
||||
.. include:: modules/raw.rst
|
||||
.. include:: modules/seboolean.rst
|
||||
.. include:: modules/selinux.rst
|
||||
.. include:: modules/service.rst
|
||||
.. include:: modules/setup.rst
|
||||
.. include:: modules/shell.rst
|
||||
.. include:: modules/slurp.rst
|
||||
.. include:: modules/subversion.rst
|
||||
.. include:: modules/supervisorctl.rst
|
||||
.. include:: modules/template.rst
|
||||
.. include:: modules/user.rst
|
||||
.. include:: modules/virt.rst
|
||||
.. include:: modules/wait_for.rst
|
||||
.. include:: modules/yum.rst
|
||||
@ -0,0 +1,92 @@
|
||||
.. _apt:
|
||||
|
||||
apt
|
||||
``````````````````````````````
|
||||
|
||||
.. versionadded:: 0.0.2
|
||||
|
||||
Manages apt-packages (such as for Debian/Ubuntu).
|
||||
|
||||
.. raw:: html
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<th class="head">parameter</th>
|
||||
<th class="head">required</th>
|
||||
<th class="head">default</th>
|
||||
<th class="head">choices</th>
|
||||
<th class="head">comments</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>purge</td>
|
||||
<td>no</td>
|
||||
<td>no</td>
|
||||
<td><ul><li>yes</li><li>no</li></ul></td>
|
||||
<td>Will force purging of configuration files if the module state is set to <code>absent</code>.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>state</td>
|
||||
<td>no</td>
|
||||
<td>present</td>
|
||||
<td><ul><li>installed</li><li>latest</li><li>remove</li><li>absent</li><li>present</li></ul></td>
|
||||
<td>Indicates the desired package state</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>force</td>
|
||||
<td>no</td>
|
||||
<td>no</td>
|
||||
<td><ul><li>yes</li><li>no</li></ul></td>
|
||||
<td>If <code>yes</code>, force installs/removes.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>pkg</td>
|
||||
<td>yes</td>
|
||||
<td></td>
|
||||
<td><ul></ul></td>
|
||||
<td>A package name or package specifier with version, like <code>foo</code> or <code>foo=1.0</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>update_cache</td>
|
||||
<td>no</td>
|
||||
<td>no</td>
|
||||
<td><ul><li>yes</li><li>no</li></ul></td>
|
||||
<td>Run the equivalent of <code>apt-get update</code> before the operation. Can be run as part of the package installation or as a seperate step</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>default_release</td>
|
||||
<td>no</td>
|
||||
<td></td>
|
||||
<td><ul></ul></td>
|
||||
<td>Corresponds to the <code>-t</code> option for <em>apt</em> and sets pin priorities</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>install_recommends</td>
|
||||
<td>no</td>
|
||||
<td>no</td>
|
||||
<td><ul><li>yes</li><li>no</li></ul></td>
|
||||
<td>Corresponds to the <code>--no-install-recommends</code> option for <em>apt</em>, default behavior works as apt's default behavior, <code>no</code> does not install recommended packages. Suggested packages are never installed.</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
.. raw:: html
|
||||
|
||||
<p>Update repositories cache and install <code>foo</code> package</p> <p><pre>
|
||||
apt pkg=foo update-cache=yes
|
||||
</pre></p>
|
||||
<p>Remove <code>foo</code> package</p> <p><pre>
|
||||
apt pkg=foo state=removed
|
||||
</pre></p>
|
||||
<p>Install the the package <code>foo</code></p> <p><pre>
|
||||
apt pkg=foo state=installed
|
||||
</pre></p>
|
||||
<p>Install the version '1.00' of package <code>foo</code></p> <p><pre>
|
||||
apt pkg=foo=1.00 state=installed
|
||||
</pre></p>
|
||||
<p>Update the repository cache and update package <code>ngnix</code> to latest version using default release <code>squeeze-backport</code></p> <p><pre>
|
||||
apt pkg=nginx state=latest default-release=squeeze-backports update-cache=yes
|
||||
</pre></p>
|
||||
<p>Install latest version of <code>openjdk-6-jdk</code> ignoring <code>install-recomands</code></p> <p><pre>
|
||||
apt pkg=openjdk-6-jdk state=latest install-recommends=no
|
||||
</pre></p>
|
||||
<br/>
|
||||
|
||||
@ -0,0 +1,51 @@
|
||||
.. _apt_repository:
|
||||
|
||||
apt_repository
|
||||
``````````````````````````````
|
||||
|
||||
.. versionadded:: 0.7
|
||||
|
||||
Manages apt repositores (such as for Debian/Ubuntu).
|
||||
|
||||
.. raw:: html
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<th class="head">parameter</th>
|
||||
<th class="head">required</th>
|
||||
<th class="head">default</th>
|
||||
<th class="head">choices</th>
|
||||
<th class="head">comments</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>repo</td>
|
||||
<td>yes</td>
|
||||
<td></td>
|
||||
<td><ul></ul></td>
|
||||
<td>The repository name/value</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>state</td>
|
||||
<td>no</td>
|
||||
<td>present</td>
|
||||
<td><ul><li>present</li><li>absent</li></ul></td>
|
||||
<td>The repository state</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
.. raw:: html
|
||||
|
||||
<p>Add nginx stable repository from PPA</p> <p><pre>
|
||||
apt_repository repo=ppa://nginx/stable
|
||||
</pre></p>
|
||||
<p>Add specified repository into sources.</p> <p><pre>
|
||||
apt_repository repo='deb http://archive.canonical.com/ubuntu hardy partner'
|
||||
</pre></p>
|
||||
<br/>
|
||||
|
||||
.. raw:: html
|
||||
|
||||
<h4>Notes</h4>
|
||||
<p>This module works on Debian and Ubuntu only and requires <code>apt-add-repository</code> be available on destination server. To ensure this package is available use the <code>apt</code> module and install the <code>python-software-properties</code> package before using this module.</p>
|
||||
<p>A bug in <code>apt-add-repository</code> always adds <code>deb</code> and <code>deb-src</code> types for repositories (see the issue on Launchpad <a href='https://bugs.launchpad.net/ubuntu/+source/software-properties/+bug/987264'>https://bugs.launchpad.net/ubuntu/+source/software-properties/+bug/987264</a>), if a repo doesn't have source information (eg MongoDB repo from 10gen) the system will fail while updating repositories.</p>
|
||||
|
||||
@ -0,0 +1,56 @@
|
||||
.. _assemble:
|
||||
|
||||
assemble
|
||||
``````````````````````````````
|
||||
|
||||
.. versionadded:: 0.5
|
||||
|
||||
Assembles a configuration file from fragments. Often a particular program will take a single configuration file and does not support a ``conf.d`` style structure where it is easy to build up the configuration from multiple sources. Assemble will take a directory of files that have already been transferred to the system, and concatenate them together to produce a destination file. Files are assembled in string sorting order. Puppet calls this idea *fragments*.
|
||||
|
||||
.. raw:: html
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<th class="head">parameter</th>
|
||||
<th class="head">required</th>
|
||||
<th class="head">default</th>
|
||||
<th class="head">choices</th>
|
||||
<th class="head">comments</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>dest</td>
|
||||
<td>yes</td>
|
||||
<td></td>
|
||||
<td><ul></ul></td>
|
||||
<td>A file to create using the concatenation of all of the source files.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>src</td>
|
||||
<td>yes</td>
|
||||
<td></td>
|
||||
<td><ul></ul></td>
|
||||
<td>An already existing directory full of source files.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>backup</td>
|
||||
<td>no</td>
|
||||
<td>no</td>
|
||||
<td><ul><li>yes</li><li>no</li></ul></td>
|
||||
<td>Create a backup file (if <code>yes</code>), including the timestamp information so you can get the original file back if you somehow clobbered it incorrectly.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>others</td>
|
||||
<td>no</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
|
||||
|
||||
<p>Example from Ansible Playbooks</p> <p><pre>
|
||||
assemble src=/etc/someapp/fragments dest=/etc/someapp/someapp.conf
|
||||
</pre></p>
|
||||
<br/>
|
||||
|
||||
@ -0,0 +1,44 @@
|
||||
.. _async_status:
|
||||
|
||||
async_status
|
||||
``````````````````````````````
|
||||
|
||||
.. versionadded:: 0.5
|
||||
|
||||
This module gets the status of an asynchronous task. See: http://ansible.cc/docs/playbooks2.html#asynchronous-actions-and-polling
|
||||
|
||||
.. raw:: html
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<th class="head">parameter</th>
|
||||
<th class="head">required</th>
|
||||
<th class="head">default</th>
|
||||
<th class="head">choices</th>
|
||||
<th class="head">comments</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>jid</td>
|
||||
<td>yes</td>
|
||||
<td></td>
|
||||
<td><ul></ul></td>
|
||||
<td>Job or task identifier</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>mode</td>
|
||||
<td>no</td>
|
||||
<td>status</td>
|
||||
<td><ul><li>status</li><li>cleanup</li></ul></td>
|
||||
<td>if <code>status</code>, obtain the status; if <code>cleanup</code>, clean up the async job cache located in <code>~/.ansible_async/</code> for the specified job <em>jid</em>.</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
.. raw:: html
|
||||
|
||||
<br/>
|
||||
|
||||
.. raw:: html
|
||||
|
||||
<h4>Notes</h4>
|
||||
<p>See <a href='http://ansible.cc/docs/playbooks2.html#asynchronous-actions-and-polling'>http://ansible.cc/docs/playbooks2.html#asynchronous-actions-and-polling</a></p>
|
||||
|
||||
@ -0,0 +1,52 @@
|
||||
.. _authorized_key:
|
||||
|
||||
authorized_key
|
||||
``````````````````````````````
|
||||
|
||||
.. versionadded:: 0.5
|
||||
|
||||
Adds or removes an SSH authorized key for a user from a remote host.
|
||||
|
||||
.. raw:: html
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<th class="head">parameter</th>
|
||||
<th class="head">required</th>
|
||||
<th class="head">default</th>
|
||||
<th class="head">choices</th>
|
||||
<th class="head">comments</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>state</td>
|
||||
<td>no</td>
|
||||
<td>present</td>
|
||||
<td><ul><li>present</li><li>absent</li></ul></td>
|
||||
<td>whether the given key should or should not be in the file</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>user</td>
|
||||
<td>yes</td>
|
||||
<td></td>
|
||||
<td><ul></ul></td>
|
||||
<td>Name of the user who should have access to the remote host</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>key</td>
|
||||
<td>yes</td>
|
||||
<td></td>
|
||||
<td><ul></ul></td>
|
||||
<td>the SSH public key, as a string</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
.. raw:: html
|
||||
|
||||
<p>Example from Ansible Playbooks</p> <p><pre>
|
||||
authorized_key user=charlie key="ssh-dss ASDF1234L+8BTwaRYr/rycsBF1D8e5pTxEsXHQs4iq+mZdyWqlW++L6pMiam1A8yweP+rKtgjK2httVS6GigVsuWWfOd7/sdWippefq74nppVUELHPKkaIOjJNN1zUHFoL/YMwAAAEBALnAsQN10TNGsRDe5arBsW8cTOjqLyYBcIqgPYTZW8zENErFxt7ij3fW3Jh/sCpnmy8rkS7FyK8ULX0PEy/2yDx8/5rXgMIICbRH/XaBy9Ud5bRBFVkEDu/r+rXP33wFPHjWjwvHAtfci1NRBAudQI/98DbcGQw5HmE89CjgZRo5ktkC5yu/8agEPocVjdHyZr7PaHfxZGUDGKtGRL2QzRYukCmWo1cZbMBHcI5FzImvTHS9/8B3SATjXMPgbfBuEeBwuBK5EjL+CtHY5bWs9kmYjmeo0KfUMH8hY4MAXDoKhQ7DhBPIrcjS5jPtoGxIREZjba67r6/P2XKXaCZH6Fc= charlie@example.org 2011-01-17"
|
||||
</pre></p>
|
||||
<p>Shorthand available in Ansible 0.8 and later</p> <p><pre>
|
||||
authorized_key user=charlie key=$FILE(/home/charlie/.ssh/id_rsa.pub)
|
||||
</pre></p>
|
||||
<br/>
|
||||
|
||||
@ -0,0 +1,64 @@
|
||||
.. _command:
|
||||
|
||||
command
|
||||
``````````````````````````````
|
||||
|
||||
|
||||
The command module takes the command name followed by a list of space-delimited arguments.
|
||||
The given command will be executed on all selected nodes. It will not be processed through the shell, so variables like ``$HOME`` and operations like ``"<"``, ``">"``, ``"|"``, and ``"&"`` will not work. As such, all paths to commands must be fully qualified
|
||||
|
||||
.. raw:: html
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<th class="head">parameter</th>
|
||||
<th class="head">required</th>
|
||||
<th class="head">default</th>
|
||||
<th class="head">choices</th>
|
||||
<th class="head">comments</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>creates</td>
|
||||
<td>no</td>
|
||||
<td></td>
|
||||
<td><ul></ul></td>
|
||||
<td>a filename, when it already exists, this step will <b>not</b> be run.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>free_form</td>
|
||||
<td>yes</td>
|
||||
<td></td>
|
||||
<td><ul></ul></td>
|
||||
<td>the command module takes a free form command to run</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>chdir</td>
|
||||
<td>no</td>
|
||||
<td></td>
|
||||
<td><ul></ul></td>
|
||||
<td>cd into this directory before running the command (added in Ansible 0.6)</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>removes</td>
|
||||
<td>no</td>
|
||||
<td></td>
|
||||
<td><ul></ul></td>
|
||||
<td>a filename, when it does not exist, this step will <b>not</b> be run. (added in Ansible 0.8)</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
.. raw:: html
|
||||
|
||||
<p>Example from Ansible Playbooks</p> <p><pre>
|
||||
command /sbin/shutdown -t now
|
||||
</pre></p>
|
||||
<p><em>creates</em>, <em>removes</em>, and <em>chdir</em> can be specified after the command. For instance, if you only want to run a command if a certain file does not exist, use this.</p> <p><pre>
|
||||
command /usr/bin/make_database.sh arg1 arg2 creates=/path/to/database
|
||||
</pre></p>
|
||||
<br/>
|
||||
|
||||
.. raw:: html
|
||||
|
||||
<h4>Notes</h4>
|
||||
<p>If you want to run a command through the shell (say you are using <code><</code>, <code>></code>, <code>|</code>, etc), you actually want the <span class='module'>shell</span> module instead. The <span class='module'>command</span> module is much more secure as it's not affected by the user's environment.</p>
|
||||
|
||||
@ -0,0 +1,58 @@
|
||||
.. _copy:
|
||||
|
||||
copy
|
||||
``````````````````````````````
|
||||
|
||||
|
||||
The ``copy`` module copies a file on the local box to remote locations.
|
||||
|
||||
.. raw:: html
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<th class="head">parameter</th>
|
||||
<th class="head">required</th>
|
||||
<th class="head">default</th>
|
||||
<th class="head">choices</th>
|
||||
<th class="head">comments</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>dest</td>
|
||||
<td>yes</td>
|
||||
<td></td>
|
||||
<td><ul></ul></td>
|
||||
<td>Remote absolute path where the file should be copied to.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>src</td>
|
||||
<td>yes</td>
|
||||
<td></td>
|
||||
<td><ul></ul></td>
|
||||
<td>Local path to a file to copy to the remote server; can be absolute or relative.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>backup</td>
|
||||
<td>no</td>
|
||||
<td>no</td>
|
||||
<td><ul><li>yes</li><li>no</li></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. (added in Ansible 0.7)</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>others</td>
|
||||
<td>no</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
|
||||
|
||||
<p>Example from Ansible Playbooks</p> <p><pre>
|
||||
copy src=/srv/myfiles/foo.conf dest=/etc/foo.conf owner=foo group=foo mode=0644
|
||||
</pre></p>
|
||||
<p>Copy a new <code>ntp.conf</code> file into place, backing up the original if it differs from the copied version</p> <p><pre>
|
||||
copy src=/mine/ntp.conf dest=/etc/ntp.conf owner=root group=root mode=644 backup=yes
|
||||
</pre></p>
|
||||
<br/>
|
||||
|
||||
@ -0,0 +1,51 @@
|
||||
.. _easy_install:
|
||||
|
||||
easy_install
|
||||
``````````````````````````````
|
||||
|
||||
.. versionadded:: 0.7
|
||||
|
||||
Installs Python libraries, optionally in a *virtualenv*
|
||||
|
||||
.. raw:: html
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<th class="head">parameter</th>
|
||||
<th class="head">required</th>
|
||||
<th class="head">default</th>
|
||||
<th class="head">choices</th>
|
||||
<th class="head">comments</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>virtualenv</td>
|
||||
<td>no</td>
|
||||
<td></td>
|
||||
<td><ul></ul></td>
|
||||
<td>an optional <em>virtualenv</em> directory path to install into. If the <em>virtualenv</em> does not exist, it is created automatically</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>name</td>
|
||||
<td>yes</td>
|
||||
<td></td>
|
||||
<td><ul></ul></td>
|
||||
<td>A Python library name</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
.. raw:: html
|
||||
|
||||
<p>Examples from Ansible Playbooks</p> <p><pre>
|
||||
easy_install name=pip
|
||||
</pre></p>
|
||||
<p>Install <em>Flask</em> (<a href='http://flask.pocoo.org/'>http://flask.pocoo.org/</a>) into the specified <em>virtualenv</em></p> <p><pre>
|
||||
easy_install name=flask virtualenv=/webapps/myapp/venv
|
||||
</pre></p>
|
||||
<br/>
|
||||
|
||||
.. raw:: html
|
||||
|
||||
<h4>Notes</h4>
|
||||
<p>Please note that the <span class='module'>easy_install</span> module can only install Python libraries. Thus this module is not able to remove libraries. It is generally recommended to use the <span class='module'>pip</span> module which you can first install using <span class='module'>easy_install</span>.</p>
|
||||
<p>Also note that <em>virtualenv</em> must be installed on the remote host if the <code>virtualenv</code> parameter is specified.</p>
|
||||
|
||||
@ -0,0 +1,17 @@
|
||||
.. _facter:
|
||||
|
||||
facter
|
||||
``````````````````````````````
|
||||
|
||||
.. versionadded:: 0.2
|
||||
|
||||
Runs the *facter* discovery program (https://github.com/puppetlabs/facter) on the remote system, returning JSON data that can be useful for inventory purposes.
|
||||
|
||||
|
||||
.. raw:: html
|
||||
|
||||
<p>Example command-line invocation</p> <p><pre>
|
||||
ansible www.example.net -m facter
|
||||
</pre></p>
|
||||
<br/>
|
||||
|
||||
@ -0,0 +1,42 @@
|
||||
.. _fail:
|
||||
|
||||
fail
|
||||
``````````````````````````````
|
||||
|
||||
.. versionadded:: 0.8
|
||||
|
||||
This module fails the progress with a custom message. It can be useful for bailing out when a certain condition is met using only_if.
|
||||
|
||||
.. raw:: html
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<th class="head">parameter</th>
|
||||
<th class="head">required</th>
|
||||
<th class="head">default</th>
|
||||
<th class="head">choices</th>
|
||||
<th class="head">comments</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>msg</td>
|
||||
<td>no</td>
|
||||
<td>Failed because only_if condition is true</td>
|
||||
<td><ul></ul></td>
|
||||
<td>The customized message used for failing execution. If ommited, fail will simple bail out with a generic message.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>rc</td>
|
||||
<td>no</td>
|
||||
<td>1</td>
|
||||
<td><ul></ul></td>
|
||||
<td>The return code of the failure. This is currently not used by Ansible, but might be used in the future.</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
.. raw:: html
|
||||
|
||||
<p>Example of how a playbook may fail when a condition is not met</p> <p><pre>
|
||||
[{'action': 'fail msg="The system may not be provisioned according to the CMDB status."', 'only_if': "'$cmdb_status' != 'to-be-staged'"}]
|
||||
</pre></p>
|
||||
<br/>
|
||||
|
||||
@ -0,0 +1,42 @@
|
||||
.. _fetch:
|
||||
|
||||
fetch
|
||||
``````````````````````````````
|
||||
|
||||
.. versionadded:: 0.2
|
||||
|
||||
This module works like ``copy``, but in reverse. It is used for fetching files from remote machines and storing them locally in a file tree, organized by hostname.
|
||||
|
||||
.. raw:: html
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<th class="head">parameter</th>
|
||||
<th class="head">required</th>
|
||||
<th class="head">default</th>
|
||||
<th class="head">choices</th>
|
||||
<th class="head">comments</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>dest</td>
|
||||
<td>yes</td>
|
||||
<td></td>
|
||||
<td><ul></ul></td>
|
||||
<td>A directory to save the file into. For example, if the <em>dest</em> directory is <code>/backup</code> a src file named <code>/etc/profile</code> on host <code>host.example.com</code>, would be saved into <code>/backup/host.example.com/etc/profile</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>src</td>
|
||||
<td>yes</td>
|
||||
<td></td>
|
||||
<td><ul></ul></td>
|
||||
<td>The file on the remote system to fetch. This must be a file, not a directory. Recursive fetching may be supported in a later release.</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
.. raw:: html
|
||||
|
||||
<p>Example from Ansible Playbooks</p> <p><pre>
|
||||
fetch src=/var/log/messages dest=/home/logtree
|
||||
</pre></p>
|
||||
<br/>
|
||||
|
||||
@ -0,0 +1,119 @@
|
||||
.. _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``.
|
||||
|
||||
.. raw:: html
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<th class="head">parameter</th>
|
||||
<th class="head">required</th>
|
||||
<th class="head">default</th>
|
||||
<th class="head">choices</th>
|
||||
<th class="head">comments</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>src</td>
|
||||
<td>no</td>
|
||||
<td></td>
|
||||
<td><ul></ul></td>
|
||||
<td>path of the file to link to (applies only to <code>state=link</code>).</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>group</td>
|
||||
<td>no</td>
|
||||
<td></td>
|
||||
<td><ul></ul></td>
|
||||
<td>name of the group that should own the file/directory, as would be fed to <em>chown</em></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>dest</td>
|
||||
<td>yes</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>selevel</td>
|
||||
<td>no</td>
|
||||
<td>s0</td>
|
||||
<td><ul></ul></td>
|
||||
<td>level part of the SELinux file context. This is the MLS/MCS attribute, sometimes known as the <code>range</code>. <code>_default</code> feature works as for <em>seuser</em>.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>seuser</td>
|
||||
<td>no</td>
|
||||
<td></td>
|
||||
<td><ul></ul></td>
|
||||
<td>user part of SELinux file context. Will default to system policy, if applicable. If set to <code>_default</code>, it will use the <code>user</code> portion of the the policy if available</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>state</td>
|
||||
<td>no</td>
|
||||
<td>file</td>
|
||||
<td><ul><li>file</li><li>link</li><li>directory</li><li>absent</li></ul></td>
|
||||
<td>If <code>directory</code>, all immediate subdirectories will be created if they do not exist. If <code>file</code>, 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 <code>link</code>, the symbolic link will be created or changed. If <code>absent</code>, directories will be recursively deleted, and files or symlinks will be unlinked.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>serole</td>
|
||||
<td>no</td>
|
||||
<td></td>
|
||||
<td><ul></ul></td>
|
||||
<td>role part of SELinux file context, <code>_default</code> feature works as for <em>seuser</em>.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>mode</td>
|
||||
<td>no</td>
|
||||
<td></td>
|
||||
<td><ul></ul></td>
|
||||
<td>mode the file or directory should be, such as 0644 as would be fed to</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>context</td>
|
||||
<td>no</td>
|
||||
<td></td>
|
||||
<td><ul><li>default</li></ul></td>
|
||||
<td>accepts only <code>default</code> as value. This will restore a file's SELinux context in the policy. Does nothing if no default value is available.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>owner</td>
|
||||
<td>no</td>
|
||||
<td></td>
|
||||
<td><ul></ul></td>
|
||||
<td>name of the user that should own the file/directory, as would be fed to <em>chown</em></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>force</td>
|
||||
<td>no</td>
|
||||
<td></td>
|
||||
<td><ul></ul></td>
|
||||
<td>force is required when changing an existing file to a directory, or a link to a directory, and so on. Use this with caution.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>setype</td>
|
||||
<td>no</td>
|
||||
<td></td>
|
||||
<td><ul></ul></td>
|
||||
<td>type part of SELinux file context, <code>_default</code> feature works as for <em>seuser</em>.</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>
|
||||
<p><pre>
|
||||
file src=/file/to/link/to dest=/path/to/symlink owner=foo group=foo state=link
|
||||
</pre></p>
|
||||
<br/>
|
||||
|
||||
.. raw:: html
|
||||
|
||||
<h4>Notes</h4>
|
||||
<p>See also <span class='module'>copy</span>, <span class='module'>template</span>, <span class='module'>assemble</span></p>
|
||||
|
||||
@ -0,0 +1,61 @@
|
||||
.. _fireball:
|
||||
|
||||
fireball
|
||||
``````````````````````````````
|
||||
|
||||
.. versionadded:: 0.9
|
||||
|
||||
This modules launches an ephemeral *fireball* ZeroMQ message bus daemon on the remote node which Ansible can to communicate with nodes at high speed.
|
||||
The daemon listens on a configurable port for a configurable amount of time.
|
||||
Starting a new fireball as a given user terminates any existing user fireballs.
|
||||
Fireball mode is AES encrypted
|
||||
|
||||
.. raw:: html
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<th class="head">parameter</th>
|
||||
<th class="head">required</th>
|
||||
<th class="head">default</th>
|
||||
<th class="head">choices</th>
|
||||
<th class="head">comments</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>minutes</td>
|
||||
<td>no</td>
|
||||
<td>30</td>
|
||||
<td><ul></ul></td>
|
||||
<td>The <em>fireball</em> listener daemon is started on nodes and will stay around for this number of minutes before turning itself off.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>port</td>
|
||||
<td>no</td>
|
||||
<td>5099</td>
|
||||
<td><ul></ul></td>
|
||||
<td>TCP port for ZeroMQ</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
.. raw:: html
|
||||
|
||||
<p>This example playbook has two plays: the first launches <em>fireball</em> mode on all hosts via SSH, and the second actually starts using <em>fireball</em> node for subsequent management over the fireball interface</p> <p><pre>
|
||||
- hosts: devservers
|
||||
gather_facts: false
|
||||
connection: ssh
|
||||
sudo: yes
|
||||
tasks:
|
||||
- action: fireball
|
||||
|
||||
- hosts: devservers
|
||||
connection: fireball
|
||||
tasks:
|
||||
- action: command /usr/bin/anything
|
||||
|
||||
</pre></p>
|
||||
<br/>
|
||||
|
||||
.. raw:: html
|
||||
|
||||
<h4>Notes</h4>
|
||||
<p>See the advanced playbooks chapter for more about using fireball mode.</p>
|
||||
|
||||
@ -0,0 +1,61 @@
|
||||
.. _get_url:
|
||||
|
||||
get_url
|
||||
``````````````````````````````
|
||||
|
||||
.. versionadded:: 0.6
|
||||
|
||||
Downloads files from HTTP, HTTPS, or FTP to the remote server. The remote server must have direct access to the remote resource.
|
||||
|
||||
.. raw:: html
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<th class="head">parameter</th>
|
||||
<th class="head">required</th>
|
||||
<th class="head">default</th>
|
||||
<th class="head">choices</th>
|
||||
<th class="head">comments</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>url</td>
|
||||
<td>yes</td>
|
||||
<td></td>
|
||||
<td><ul></ul></td>
|
||||
<td>HTTP, HTTPS, or FTP URL</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>dest</td>
|
||||
<td>yes</td>
|
||||
<td></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>no</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. (added in Ansible 0.7)</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>others</td>
|
||||
<td>no</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
|
||||
|
||||
<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/>
|
||||
|
||||
.. raw:: html
|
||||
|
||||
<h4>Notes</h4>
|
||||
<p>This module doesn't yet support configuration for proxies or passwords.</p>
|
||||
|
||||
@ -0,0 +1,63 @@
|
||||
.. _git:
|
||||
|
||||
git
|
||||
``````````````````````````````
|
||||
|
||||
.. versionadded:: 0.0.1
|
||||
|
||||
Manage git checkouts of repositories to deploy files or software.
|
||||
|
||||
.. raw:: html
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<th class="head">parameter</th>
|
||||
<th class="head">required</th>
|
||||
<th class="head">default</th>
|
||||
<th class="head">choices</th>
|
||||
<th class="head">comments</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>repo</td>
|
||||
<td>yes</td>
|
||||
<td></td>
|
||||
<td><ul></ul></td>
|
||||
<td>git, ssh, or http protocol address of the git repository.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>dest</td>
|
||||
<td>yes</td>
|
||||
<td></td>
|
||||
<td><ul></ul></td>
|
||||
<td>Absolute path of where the repository should be checked out to.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>version</td>
|
||||
<td>no</td>
|
||||
<td>HEAD</td>
|
||||
<td><ul></ul></td>
|
||||
<td>What version of the repository to check out. This can be the git <em>SHA</em>, the literal string <em>HEAD</em>, branch name, or a tag name.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>force</td>
|
||||
<td>no</td>
|
||||
<td>yes</td>
|
||||
<td><ul><li>True</li><li>False</li></ul></td>
|
||||
<td>(New in 0.7) If yes, any modified files in the working repository will be discarded. Prior to 0.7, this was always 'yes' and could not be disabled.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>remote</td>
|
||||
<td>no</td>
|
||||
<td>origin</td>
|
||||
<td><ul></ul></td>
|
||||
<td>Name of the remote branch.</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
.. raw:: html
|
||||
|
||||
<p>Example git checkout from Ansible Playbooks</p> <p><pre>
|
||||
git repo=git://foosball.example.org/path/to/repo.git dest=/srv/checkout version=release-0.22
|
||||
</pre></p>
|
||||
<br/>
|
||||
|
||||
@ -0,0 +1,56 @@
|
||||
.. _group:
|
||||
|
||||
group
|
||||
``````````````````````````````
|
||||
|
||||
.. versionadded:: 0.0.2
|
||||
|
||||
Manage presence of groups on a host.
|
||||
|
||||
.. raw:: html
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<th class="head">parameter</th>
|
||||
<th class="head">required</th>
|
||||
<th class="head">default</th>
|
||||
<th class="head">choices</th>
|
||||
<th class="head">comments</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>state</td>
|
||||
<td>no</td>
|
||||
<td>present</td>
|
||||
<td><ul><li>present</li><li>absent</li></ul></td>
|
||||
<td>Whether the group should be present or not on the remote host.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>gid</td>
|
||||
<td>no</td>
|
||||
<td></td>
|
||||
<td><ul></ul></td>
|
||||
<td>Optional <em>GID</em> to set for the group.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>name</td>
|
||||
<td>yes</td>
|
||||
<td></td>
|
||||
<td><ul></ul></td>
|
||||
<td>Name of the group to manage.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>system</td>
|
||||
<td>no</td>
|
||||
<td>no</td>
|
||||
<td><ul><li>True</li><li>False</li></ul></td>
|
||||
<td>If <em>yes</em>, indicates that the group created is a system group.</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
.. raw:: html
|
||||
|
||||
<p>Example group command from Ansible Playbooks</p> <p><pre>
|
||||
group name=somegroup state=present
|
||||
</pre></p>
|
||||
<br/>
|
||||
|
||||
@ -0,0 +1,83 @@
|
||||
.. _ini_file:
|
||||
|
||||
ini_file
|
||||
``````````````````````````````
|
||||
|
||||
.. versionadded:: 0.9
|
||||
|
||||
Manage (add, remove, change) individual settings in an INI-style file without having to manage the file as a whole with, say, ``template`` or ``assemble``. Adds missing sections if they don't exist.
|
||||
|
||||
.. raw:: html
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<th class="head">parameter</th>
|
||||
<th class="head">required</th>
|
||||
<th class="head">default</th>
|
||||
<th class="head">choices</th>
|
||||
<th class="head">comments</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>option</td>
|
||||
<td>no</td>
|
||||
<td></td>
|
||||
<td><ul></ul></td>
|
||||
<td>if set (required for changing a <em>value</em>), this is the name of the option.May be omitted if adding/removing a whole <em>section</em>.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>others</td>
|
||||
<td>no</td>
|
||||
<td></td>
|
||||
<td><ul></ul></td>
|
||||
<td>all arguments accepted by the <span class='module'>file</span> module also work here</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>dest</td>
|
||||
<td>yes</td>
|
||||
<td></td>
|
||||
<td><ul></ul></td>
|
||||
<td>Path to the INI-style file; this file is created if required</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>section</td>
|
||||
<td>yes</td>
|
||||
<td></td>
|
||||
<td><ul></ul></td>
|
||||
<td>Section name in INI file. This is added if <code>state=present</code> automatically when a single value is being set.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>backup</td>
|
||||
<td>no</td>
|
||||
<td></td>
|
||||
<td><ul><li>yes</li><li>no</li></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>
|
||||
<tr>
|
||||
<td>value</td>
|
||||
<td>no</td>
|
||||
<td></td>
|
||||
<td><ul></ul></td>
|
||||
<td>the string value to be associated with an <em>option</em>. May be omitted when removing an <em>option</em>.</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
.. raw:: html
|
||||
|
||||
<p>Ensure <code>fav=lemonade</code> is in section <code>[drinks]</code> in said file</p> <p><pre>
|
||||
ini_file dest=/etc/conf section=drinks option=fav value=lemonade mode=0600 backup=true
|
||||
</pre></p>
|
||||
<p><pre>
|
||||
ini_file dest=/etc/anotherconf
|
||||
section=drinks
|
||||
option=temperature
|
||||
value=cold
|
||||
backup=true
|
||||
|
||||
</pre></p>
|
||||
<br/>
|
||||
|
||||
.. raw:: html
|
||||
|
||||
<h4>Notes</h4>
|
||||
<p>While it is possible to add an <em>option</em> without specifying a <em>value</em>, this makes no sense.</p>
|
||||
|
||||
@ -0,0 +1,74 @@
|
||||
.. _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 want to change a single line in a file only. For other cases, see the ``copy`` or ``template`` modules.
|
||||
|
||||
.. raw:: html
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<th class="head">parameter</th>
|
||||
<th class="head">required</th>
|
||||
<th class="head">default</th>
|
||||
<th class="head">choices</th>
|
||||
<th class="head">comments</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>state</td>
|
||||
<td>no</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>yes</td>
|
||||
<td></td>
|
||||
<td><ul></ul></td>
|
||||
<td>The file to modify</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>insertafter</td>
|
||||
<td>no</td>
|
||||
<td>EOF</td>
|
||||
<td><ul><li>BOF</li><li>EOF</li></ul></td>
|
||||
<td>Used with <code>state=present</code>. 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>yes</td>
|
||||
<td></td>
|
||||
<td><ul></ul></td>
|
||||
<td>The regular expression to look for in the file. For <code>state=present</code>, the pattern to replace. For <code>state=absent</code>, the pattern of the line to remove.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>line</td>
|
||||
<td>no</td>
|
||||
<td></td>
|
||||
<td><ul></ul></td>
|
||||
<td>Required for <code>state=present</code>. The line to insert/replace into the file. Must match the value given to <code>regexp</code>.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>backup</td>
|
||||
<td>no</td>
|
||||
<td></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><pre>
|
||||
lineinfile name=/etc/selinux/config regexp=^SELINUX= line=SELINUX=disabled
|
||||
</pre></p>
|
||||
<p><pre>
|
||||
lineinfile name=/etc/sudoers state=absent regexp="^%wheel"
|
||||
</pre></p>
|
||||
<br/>
|
||||
|
||||
@ -0,0 +1,77 @@
|
||||
.. _mount:
|
||||
|
||||
mount
|
||||
``````````````````````````````
|
||||
|
||||
.. versionadded:: 0.6
|
||||
|
||||
This module controls active and configured mount points in ``/etc/fstab``.
|
||||
|
||||
.. raw:: html
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<th class="head">parameter</th>
|
||||
<th class="head">required</th>
|
||||
<th class="head">default</th>
|
||||
<th class="head">choices</th>
|
||||
<th class="head">comments</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>src</td>
|
||||
<td>yes</td>
|
||||
<td></td>
|
||||
<td><ul></ul></td>
|
||||
<td>device to be mounted on <em>name</em>.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>state</td>
|
||||
<td>yes</td>
|
||||
<td></td>
|
||||
<td><ul><li>present</li><li>absent</li><li>mounted</li><li>unmounted</li></ul></td>
|
||||
<td>If <code>mounted</code> or <code>unmounted</code>, the device will be actively mounted or unmounted as well as just configured in <em>fstab</em>. <code>absent</code> and <code>present</code> only deal with <em>fstab</em>.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>name</td>
|
||||
<td>yes</td>
|
||||
<td></td>
|
||||
<td><ul></ul></td>
|
||||
<td>path to the mount point, eg: <code>/mnt/files</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>dump</td>
|
||||
<td>no</td>
|
||||
<td></td>
|
||||
<td><ul></ul></td>
|
||||
<td>dump (see fstab(8))</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>passno</td>
|
||||
<td>no</td>
|
||||
<td></td>
|
||||
<td><ul></ul></td>
|
||||
<td>passno (see fstab(8))</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>opts</td>
|
||||
<td>no</td>
|
||||
<td></td>
|
||||
<td><ul></ul></td>
|
||||
<td>mount options (see fstab(8))</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>fstype</td>
|
||||
<td>yes</td>
|
||||
<td></td>
|
||||
<td><ul></ul></td>
|
||||
<td>file-system type</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
.. raw:: html
|
||||
|
||||
<p>Mount DVD read-only</p> <p><pre>
|
||||
mount name=/mnt/dvd src=/dev/sr0 fstype=iso9660 opts=ro
|
||||
</pre></p>
|
||||
<br/>
|
||||
|
||||
@ -0,0 +1,83 @@
|
||||
.. _mysql_db:
|
||||
|
||||
mysql_db
|
||||
``````````````````````````````
|
||||
|
||||
.. versionadded:: 0.6
|
||||
|
||||
Add or remove MySQL databases from a remote host.
|
||||
|
||||
.. raw:: html
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<th class="head">parameter</th>
|
||||
<th class="head">required</th>
|
||||
<th class="head">default</th>
|
||||
<th class="head">choices</th>
|
||||
<th class="head">comments</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>state</td>
|
||||
<td>no</td>
|
||||
<td>present</td>
|
||||
<td><ul><li>present</li><li>absent</li></ul></td>
|
||||
<td>The database state</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>name</td>
|
||||
<td>yes</td>
|
||||
<td></td>
|
||||
<td><ul></ul></td>
|
||||
<td>name of the database to add or remove</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>encoding</td>
|
||||
<td>no</td>
|
||||
<td></td>
|
||||
<td><ul></ul></td>
|
||||
<td>Encoding mode</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>collation</td>
|
||||
<td>no</td>
|
||||
<td></td>
|
||||
<td><ul></ul></td>
|
||||
<td>Collation mode</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>login_user</td>
|
||||
<td>no</td>
|
||||
<td></td>
|
||||
<td><ul></ul></td>
|
||||
<td>The username used to authenticate with</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>login_host</td>
|
||||
<td>no</td>
|
||||
<td>localhost</td>
|
||||
<td><ul></ul></td>
|
||||
<td>Host running the database</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>login_password</td>
|
||||
<td>no</td>
|
||||
<td></td>
|
||||
<td><ul></ul></td>
|
||||
<td>The password used to authenticate with</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
.. raw:: html
|
||||
|
||||
<p>Create a new database with name 'bobdata'</p> <p><pre>
|
||||
mysql_db db=bobdata state=present
|
||||
</pre></p>
|
||||
<br/>
|
||||
|
||||
.. raw:: html
|
||||
|
||||
<h4>Notes</h4>
|
||||
<p>Requires the MySQLdb Python package on the remote host. For Ubuntu, this is as easy as apt-get install python-mysqldb.</p>
|
||||
<p>Both <code>login_password</code> and <code>login_username</code> are required when you are passing credentials. If none are present, the module will attempt to read the credentials from <code>~/.my.cnf</code>, and finally fall back to using the MySQL default login of 'root' with no password.</p>
|
||||
|
||||
@ -0,0 +1,96 @@
|
||||
.. _mysql_user:
|
||||
|
||||
mysql_user
|
||||
``````````````````````````````
|
||||
|
||||
.. versionadded:: 0.6
|
||||
|
||||
Adds or removes a user from a MySQL database.
|
||||
|
||||
.. raw:: html
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<th class="head">parameter</th>
|
||||
<th class="head">required</th>
|
||||
<th class="head">default</th>
|
||||
<th class="head">choices</th>
|
||||
<th class="head">comments</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>name</td>
|
||||
<td>yes</td>
|
||||
<td></td>
|
||||
<td><ul></ul></td>
|
||||
<td>name of the user (role) to add or remove</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>login_user</td>
|
||||
<td>no</td>
|
||||
<td></td>
|
||||
<td><ul></ul></td>
|
||||
<td>The username used to authenticate with</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>login_host</td>
|
||||
<td>no</td>
|
||||
<td>localhost</td>
|
||||
<td><ul></ul></td>
|
||||
<td>Host running the database</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>host</td>
|
||||
<td>no</td>
|
||||
<td>localhost</td>
|
||||
<td><ul></ul></td>
|
||||
<td>the 'host' part of the MySQL username</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>state</td>
|
||||
<td>no</td>
|
||||
<td>present</td>
|
||||
<td><ul><li>present</li><li>absent</li></ul></td>
|
||||
<td>The database state</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>login_password</td>
|
||||
<td>no</td>
|
||||
<td></td>
|
||||
<td><ul></ul></td>
|
||||
<td>The password used to authenticate with</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>password</td>
|
||||
<td>no</td>
|
||||
<td></td>
|
||||
<td><ul></ul></td>
|
||||
<td>set the user's password</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>priv</td>
|
||||
<td>no</td>
|
||||
<td></td>
|
||||
<td><ul></ul></td>
|
||||
<td>MySQL privileges string in the format: <code>db.table:priv1,priv2</code></td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
.. raw:: html
|
||||
|
||||
<p>Create database user with name 'bob' and password '12345' with all database privileges</p> <p><pre>
|
||||
mysql_user name=bob password=12345 priv=*.*:ALL state=present
|
||||
</pre></p>
|
||||
<p>Ensure no user named 'sally' exists, also passing in the auth credentials.</p> <p><pre>
|
||||
mysql_user login_user=root login_password=123456 name=sally state=absent
|
||||
</pre></p>
|
||||
<p>Example privileges string format</p> <p><pre>
|
||||
mydb.*:INSERT,UPDATE/anotherdb.*:SELECT/yetanotherdb.*:ALL
|
||||
</pre></p>
|
||||
<br/>
|
||||
|
||||
.. raw:: html
|
||||
|
||||
<h4>Notes</h4>
|
||||
<p>Requires the MySQLdb Python package on the remote host. For Ubuntu, this is as easy as apt-get install python-mysqldb.</p>
|
||||
<p>Both <code>login_password</code> and <code>login_username</code> are required when you are passing credentials. If none are present, the module will attempt to read the credentials from <code>~/.my.cnf</code>, and finally fall back to using the MySQL default login of 'root' with no password.</p>
|
||||
|
||||
@ -0,0 +1,95 @@
|
||||
.. _nagios:
|
||||
|
||||
nagios
|
||||
``````````````````````````````
|
||||
|
||||
.. versionadded:: 0.7
|
||||
|
||||
The ``nagios`` module has two basic functions: scheduling downtime and toggling alerts for services or hosts.
|
||||
All actions require the ``host`` parameter to be given explicitly. In playbooks you can use the ``$inventory_hostname`` variable to refer to the host the playbook is currently running on.
|
||||
You can specify multiple services at once by separating them with commas, .e.g., ``services=httpd,nfs,puppet``.
|
||||
When specifying what service to handle there is a special service value, *host*, which will handle alerts/downtime for the *host itself*, e.g., ``service=host``. This keyword may not be given with other services at the same time. *Setting alerts/downtime for a host does not affect alerts/downtime for any of the services running on it.*
|
||||
When using the ``nagios`` module you will need to specify your nagios server using the ``delegate_to`` parameter.
|
||||
|
||||
.. raw:: html
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<th class="head">parameter</th>
|
||||
<th class="head">required</th>
|
||||
<th class="head">default</th>
|
||||
<th class="head">choices</th>
|
||||
<th class="head">comments</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>action</td>
|
||||
<td>yes</td>
|
||||
<td></td>
|
||||
<td><ul><li>downtime</li><li>enable_alerts</li><li>disable_alerts</li><li>silence</li><li>unsilence</li></ul></td>
|
||||
<td>Action to take.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>host</td>
|
||||
<td>yes</td>
|
||||
<td></td>
|
||||
<td><ul></ul></td>
|
||||
<td>Host to operate on in Nagios.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>author</td>
|
||||
<td>no</td>
|
||||
<td>Ansible</td>
|
||||
<td><ul></ul></td>
|
||||
<td>Author to leave downtime comments as. - Only useable with the <code>downtime</code> action.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>services</td>
|
||||
<td>yes</td>
|
||||
<td></td>
|
||||
<td><ul></ul></td>
|
||||
<td>What to manage downtime/alerts for. Separate multiple services with commas.<code>service</code> is an alias for <code>services</code>.<b>Required</b> option when using the <code>downtime</code>, <code>enable_alerts</code>, and <code>disable_alerts</code> actions.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>minutes</td>
|
||||
<td>no</td>
|
||||
<td>30</td>
|
||||
<td><ul></ul></td>
|
||||
<td>Minutes to schedule downtime for.Only useable with the <code>downtime</code> action.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>cmdfile</td>
|
||||
<td>no</td>
|
||||
<td>auto-detected</td>
|
||||
<td><ul></ul></td>
|
||||
<td>Path to the nagios <em>command file</em> (FIFO pipe).Only required if auto-detection fails.</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
.. raw:: html
|
||||
|
||||
<p>set 30 minutes of apache downtime</p> <p><pre>
|
||||
nagios action=downtime minutes=30 service=httpd host=$inventory_hostname
|
||||
</pre></p>
|
||||
<p>schedule an hour of HOST downtime</p> <p><pre>
|
||||
nagios action=downtime minutes=60 service=host host=$inventory_hostname
|
||||
</pre></p>
|
||||
<p>schedule downtime for a few services</p> <p><pre>
|
||||
nagios action=downtime services=frob,foobar,qeuz host=$inventory_hostname
|
||||
</pre></p>
|
||||
<p>enable SMART disk alerts</p> <p><pre>
|
||||
nagios action=enable_alerts service=smart host=$inventory_hostname
|
||||
</pre></p>
|
||||
<p>two services at once: disable httpd and nfs alerts</p> <p><pre>
|
||||
nagios action=disable_alerts service=httpd,nfs host=$inventory_hostname
|
||||
</pre></p>
|
||||
<p>disable HOST alerts</p> <p><pre>
|
||||
nagios action=disable_alerts service=host host=$inventory_hostname
|
||||
</pre></p>
|
||||
<p>silence ALL alerts</p> <p><pre>
|
||||
nagios action=silence host=$inventory_hostname
|
||||
</pre></p>
|
||||
<p>unsilence all alerts</p> <p><pre>
|
||||
nagios action=unsilence host=$inventory_hostname
|
||||
</pre></p>
|
||||
<br/>
|
||||
|
||||
@ -0,0 +1,17 @@
|
||||
.. _ohai:
|
||||
|
||||
ohai
|
||||
``````````````````````````````
|
||||
|
||||
.. versionadded:: 0.6
|
||||
|
||||
Similar to the ``facter`` module, this runs the *ohai* discovery program (http://wiki.opscode.com/display/chef/Ohai) on the remote host and returns JSON inventory data. *Ohai* data is a bit more verbose and nested than *facter*.
|
||||
|
||||
|
||||
.. raw:: html
|
||||
|
||||
<p>Retrieve <em>ohai</em> data from all Web servers and store in one-file per host</p> <p><pre>
|
||||
ansible webservers -m ohai --tree=/tmp/ohaidata
|
||||
</pre></p>
|
||||
<br/>
|
||||
|
||||
@ -0,0 +1,57 @@
|
||||
.. _pause:
|
||||
|
||||
pause
|
||||
``````````````````````````````
|
||||
|
||||
.. versionadded:: 0.8
|
||||
|
||||
Pauses playbook execution for a set amount of time, or until a prompt is acknowledged. All parameters are optional. The default behavior is to pause with a prompt.
|
||||
You can use ``ctrl+c`` if you wish to advance a pause earlier than it is set to expire or if you need to abort a playbook run entirely. To continue early: press ``ctrl+c`` and then ``c``. To abort a playbook: press ``ctrl+c`` and then ``a``.
|
||||
The pause module integrates into async/parallelized playbooks without any special considerations (see also: Rolling Updates). When using pauses with the ``serial`` playbook parameter (as in rolling updates) you are only prompted once for the current group of hosts.
|
||||
|
||||
.. raw:: html
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<th class="head">parameter</th>
|
||||
<th class="head">required</th>
|
||||
<th class="head">default</th>
|
||||
<th class="head">choices</th>
|
||||
<th class="head">comments</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>seconds</td>
|
||||
<td>no</td>
|
||||
<td></td>
|
||||
<td><ul></ul></td>
|
||||
<td>Number of minutes to pause for.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>minutes</td>
|
||||
<td>no</td>
|
||||
<td></td>
|
||||
<td><ul></ul></td>
|
||||
<td>Number of minutes to pause for.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>prompt</td>
|
||||
<td>no</td>
|
||||
<td></td>
|
||||
<td><ul></ul></td>
|
||||
<td>Optional text to use for the prompt message.</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
.. raw:: html
|
||||
|
||||
<p>Pause for 5 minutes to build app cache.</p> <p><pre>
|
||||
pause minutes=5
|
||||
</pre></p>
|
||||
<p>Pause until you can verify updates to an application were successful.</p> <p><pre>
|
||||
pause
|
||||
</pre></p>
|
||||
<p>A helpful reminder of what to look out for post-update.</p> <p><pre>
|
||||
pause prompt=Make sure org.foo.FooOverload exception is not present
|
||||
</pre></p>
|
||||
<br/>
|
||||
|
||||
@ -0,0 +1,16 @@
|
||||
.. _ping:
|
||||
|
||||
ping
|
||||
``````````````````````````````
|
||||
|
||||
|
||||
A trivial test module, this module always returns 'pong' on successful contact. It does not make sense in playbooks, but is useful from ``/usr/bin/ansible``
|
||||
|
||||
|
||||
.. raw:: html
|
||||
|
||||
<p>Test 'webservers' status</p> <p><pre>
|
||||
ansible webservers -m ping
|
||||
</pre></p>
|
||||
<br/>
|
||||
|
||||
@ -0,0 +1,80 @@
|
||||
.. _pip:
|
||||
|
||||
pip
|
||||
``````````````````````````````
|
||||
|
||||
.. versionadded:: 0.7
|
||||
|
||||
Manage Python library dependencies.
|
||||
|
||||
.. raw:: html
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<th class="head">parameter</th>
|
||||
<th class="head">required</th>
|
||||
<th class="head">default</th>
|
||||
<th class="head">choices</th>
|
||||
<th class="head">comments</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>virtualenv</td>
|
||||
<td>no</td>
|
||||
<td></td>
|
||||
<td><ul></ul></td>
|
||||
<td>An optional path to a virtualenv directory to install into</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>state</td>
|
||||
<td>no</td>
|
||||
<td>present</td>
|
||||
<td><ul><li>present</li><li>absent</li><li>latest</li></ul></td>
|
||||
<td>The state of module</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>version</td>
|
||||
<td>no</td>
|
||||
<td></td>
|
||||
<td><ul></ul></td>
|
||||
<td>The version number to install of the Python library specified in the 'name' parameter</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>requirements</td>
|
||||
<td>no</td>
|
||||
<td></td>
|
||||
<td><ul></ul></td>
|
||||
<td>The path to a pip requirements file</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>name</td>
|
||||
<td>yes</td>
|
||||
<td></td>
|
||||
<td><ul></ul></td>
|
||||
<td>The name of a Python library to install</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
.. raw:: html
|
||||
|
||||
<p>Install <em>flask</em> python package.</p> <p><pre>
|
||||
pip name=flask
|
||||
</pre></p>
|
||||
<p>Install <em>flask</em> python package on version 0.8.</p> <p><pre>
|
||||
pip name=flask version=0.8
|
||||
</pre></p>
|
||||
<p>Install <em>Flask</em> (<a href='http://flask.pocoo.org/'>http://flask.pocoo.org/</a>) into the specified <em>virtualenv</em></p> <p><pre>
|
||||
pip name=flask virtualenv=/srv/webapps/my_app/venv
|
||||
</pre></p>
|
||||
<p>Install specified python requirements.</p> <p><pre>
|
||||
pip requirements=/srv/webapps/my_app/src/requirements.txt
|
||||
</pre></p>
|
||||
<p>Install specified python requirements in indicated virtualenv.</p> <p><pre>
|
||||
pip requirements=/srv/webapps/my_app/src/requirements.txt virtualenv=/srv/webapps/my_app/venv
|
||||
</pre></p>
|
||||
<br/>
|
||||
|
||||
.. raw:: html
|
||||
|
||||
<h4>Notes</h4>
|
||||
<p>Please note that <a href='http://www.virtualenv.org/, virtualenv'>http://www.virtualenv.org/, virtualenv</a> must be installed on the remote host if the virtualenv parameter is specified.</p>
|
||||
|
||||
@ -0,0 +1,76 @@
|
||||
.. _postgresql_db:
|
||||
|
||||
postgresql_db
|
||||
``````````````````````````````
|
||||
|
||||
.. versionadded:: 0.6
|
||||
|
||||
Add or remove PostgreSQL databases from a remote host.
|
||||
|
||||
.. raw:: html
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<th class="head">parameter</th>
|
||||
<th class="head">required</th>
|
||||
<th class="head">default</th>
|
||||
<th class="head">choices</th>
|
||||
<th class="head">comments</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>state</td>
|
||||
<td>no</td>
|
||||
<td>present</td>
|
||||
<td><ul><li>present</li><li>absent</li></ul></td>
|
||||
<td>The database state</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>name</td>
|
||||
<td>yes</td>
|
||||
<td></td>
|
||||
<td><ul></ul></td>
|
||||
<td>name of the database to add or remove</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>login_password</td>
|
||||
<td>no</td>
|
||||
<td></td>
|
||||
<td><ul></ul></td>
|
||||
<td>The password used to authenticate with</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>owner</td>
|
||||
<td>no</td>
|
||||
<td></td>
|
||||
<td><ul></ul></td>
|
||||
<td>Name of the role to set as owner of the database</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>login_user</td>
|
||||
<td>no</td>
|
||||
<td></td>
|
||||
<td><ul></ul></td>
|
||||
<td>The username used to authenticate with</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>login_host</td>
|
||||
<td>no</td>
|
||||
<td>localhost</td>
|
||||
<td><ul></ul></td>
|
||||
<td>Host running the database</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
.. raw:: html
|
||||
|
||||
<p>Create a new database with name 'acme'</p> <p><pre>
|
||||
postgresql_db db=acme
|
||||
</pre></p>
|
||||
<br/>
|
||||
|
||||
.. raw:: html
|
||||
|
||||
<h4>Notes</h4>
|
||||
<p>The default authentication assumes that you are either logging in as or sudo'ing to the postgres account on the host.</p>
|
||||
<p>This module uses psycopg2, a Python PostgreSQL database adapter. You must ensure that psycopg2 is installed on the host before using this module. If the remote host is the PostgreSQL server (which is the default case), then PostgreSQL must also be installed on the remote host. For Ubuntu-based systems, install the postgresql, libpq-dev, and python-psycopg2 packages on the remote host before using this module.</p>
|
||||
|
||||
@ -0,0 +1,108 @@
|
||||
.. _postgresql_user:
|
||||
|
||||
postgresql_user
|
||||
``````````````````````````````
|
||||
|
||||
.. versionadded:: 0.6
|
||||
|
||||
Add or remove PostgreSQL users (roles) from a remote host and, optionally, grant the users access to an existing database or tables.
|
||||
The fundamental function of the module is to create, or delete, roles from a PostgreSQL cluster. Privilege assignment, or removal, is an optional step, which works on one database at a time. This allows for the module to be called several times in the same module to modify the permissions on different databases, or to grant permissions to already existing users.
|
||||
A user cannot be removed untill all the privileges have been stripped from the user. In such situation, if the module tries to remove the user it will fail. To avoid this from happening the fail_on_user option signals the module to try to remove the user, but if not possible keep going; the module will report if changes happened and separately if the user was removed or not.
|
||||
|
||||
.. raw:: html
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<th class="head">parameter</th>
|
||||
<th class="head">required</th>
|
||||
<th class="head">default</th>
|
||||
<th class="head">choices</th>
|
||||
<th class="head">comments</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>name</td>
|
||||
<td>yes</td>
|
||||
<td></td>
|
||||
<td><ul></ul></td>
|
||||
<td>name of the user (role) to add or remove</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>login_user</td>
|
||||
<td>no</td>
|
||||
<td>postgres</td>
|
||||
<td><ul></ul></td>
|
||||
<td>User (role) used to authenticate with PostgreSQL</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>login_host</td>
|
||||
<td>no</td>
|
||||
<td>localhost</td>
|
||||
<td><ul></ul></td>
|
||||
<td>Host running PostgreSQL.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>db</td>
|
||||
<td>no</td>
|
||||
<td></td>
|
||||
<td><ul></ul></td>
|
||||
<td>name of database where permissions will be granted</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>state</td>
|
||||
<td>no</td>
|
||||
<td>present</td>
|
||||
<td><ul><li>present</li><li>absent</li></ul></td>
|
||||
<td>The database state</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>login_password</td>
|
||||
<td>no</td>
|
||||
<td></td>
|
||||
<td><ul></ul></td>
|
||||
<td>Password used to authenticate with PostgreSQL</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>password</td>
|
||||
<td>yes</td>
|
||||
<td></td>
|
||||
<td><ul></ul></td>
|
||||
<td>set the user's password</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>fail_on_user</td>
|
||||
<td>no</td>
|
||||
<td>True</td>
|
||||
<td><ul><li>yes</li><li>no</li></ul></td>
|
||||
<td>if yes, fail when user can't be removed. Otherwise just log and continue</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>priv</td>
|
||||
<td>no</td>
|
||||
<td></td>
|
||||
<td><ul></ul></td>
|
||||
<td>PostgreSQL privileges string in the format: <code>table:priv1,priv2</code></td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
.. raw:: html
|
||||
|
||||
<p>Create django user and grant access to database and products table</p> <p><pre>
|
||||
postgresql_user db=acme user=django password=ceec4eif7ya priv=CONNECT/products:ALL
|
||||
</pre></p>
|
||||
<p>Remove test user privileges from acme</p> <p><pre>
|
||||
postgresql_user db=acme user=test priv=ALL/products:ALL state=absent fail_on_user=no
|
||||
</pre></p>
|
||||
<p>Remove test user from test database and the cluster</p> <p><pre>
|
||||
postgresql_user db=test user=test priv=ALL state=absent
|
||||
</pre></p>
|
||||
<p>Example privileges string format</p> <p><pre>
|
||||
INSERT,UPDATE/table:SELECT/anothertable:ALL
|
||||
</pre></p>
|
||||
<br/>
|
||||
|
||||
.. raw:: html
|
||||
|
||||
<h4>Notes</h4>
|
||||
<p>The default authentication assumes that you are either logging in as or sudo'ing to the postgres account on the host.</p>
|
||||
<p>This module uses psycopg2, a Python PostgreSQL database adapter. You must ensure that psycopg2 is installed on the host before using this module. If the remote host is the PostgreSQL server (which is the default case), then PostgreSQL must also be installed on the remote host. For Ubuntu-based systems, install the postgresql, libpq-dev, and python-psycopg2 packages on the remote host before using this module.</p>
|
||||
|
||||
@ -0,0 +1,16 @@
|
||||
.. _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
|
||||
|
||||
|
||||
.. 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/>
|
||||
|
||||
@ -0,0 +1,54 @@
|
||||
.. _seboolean:
|
||||
|
||||
seboolean
|
||||
``````````````````````````````
|
||||
|
||||
.. versionadded:: 0.7
|
||||
|
||||
Toggles SELinux booleans.
|
||||
|
||||
.. raw:: html
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<th class="head">parameter</th>
|
||||
<th class="head">required</th>
|
||||
<th class="head">default</th>
|
||||
<th class="head">choices</th>
|
||||
<th class="head">comments</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>state</td>
|
||||
<td>yes</td>
|
||||
<td></td>
|
||||
<td><ul><li>true</li><li>false</li></ul></td>
|
||||
<td>Desired boolean value</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>name</td>
|
||||
<td>yes</td>
|
||||
<td></td>
|
||||
<td><ul></ul></td>
|
||||
<td>Name of the boolean to configure</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>persistent</td>
|
||||
<td>no</td>
|
||||
<td></td>
|
||||
<td><ul><li>yes</li><li>no</li></ul></td>
|
||||
<td>Set to 'yes' if the boolean setting should survive a reboot</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
.. raw:: html
|
||||
|
||||
<p>Set <em>httpd_can_network_connect</em> SELinux flag to <em>true</em> and <em>persistent</em></p> <p><pre>
|
||||
seboolean name=httpd_can_network_connect state=true persistent=yes
|
||||
</pre></p>
|
||||
<br/>
|
||||
|
||||
.. raw:: html
|
||||
|
||||
<h4>Notes</h4>
|
||||
<p>Not tested on any debian based system</p>
|
||||
|
||||
@ -0,0 +1,57 @@
|
||||
.. _selinux:
|
||||
|
||||
selinux
|
||||
``````````````````````````````
|
||||
|
||||
.. versionadded:: 0.7
|
||||
|
||||
Configures the SELinux mode and policy. A reboot may be required after usage. Ansible will not issue this reboot but will let you know when it is required.
|
||||
|
||||
.. raw:: html
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<th class="head">parameter</th>
|
||||
<th class="head">required</th>
|
||||
<th class="head">default</th>
|
||||
<th class="head">choices</th>
|
||||
<th class="head">comments</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>policy</td>
|
||||
<td>yes</td>
|
||||
<td></td>
|
||||
<td><ul></ul></td>
|
||||
<td>name of the SELinux policy to use (example: 'targeted')</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>state</td>
|
||||
<td>yes</td>
|
||||
<td></td>
|
||||
<td><ul><li>enforcing</li><li>permissive</li><li>disabled</li></ul></td>
|
||||
<td>The SELinux mode</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>conf</td>
|
||||
<td>no</td>
|
||||
<td>/etc/selinux/config</td>
|
||||
<td><ul></ul></td>
|
||||
<td>path to the SELinux configuration file, if non-standard</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
.. raw:: html
|
||||
|
||||
<p><pre>
|
||||
selinux policy=targeted state=enforcing
|
||||
</pre></p>
|
||||
<p><pre>
|
||||
selinux policy=targeted state=disabled
|
||||
</pre></p>
|
||||
<br/>
|
||||
|
||||
.. raw:: html
|
||||
|
||||
<h4>Notes</h4>
|
||||
<p>Not tested on any debian based system</p>
|
||||
|
||||
@ -0,0 +1,68 @@
|
||||
.. _service:
|
||||
|
||||
service
|
||||
``````````````````````````````
|
||||
|
||||
.. versionadded:: 0.1
|
||||
|
||||
Controls services on remote hosts.
|
||||
|
||||
.. raw:: html
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<th class="head">parameter</th>
|
||||
<th class="head">required</th>
|
||||
<th class="head">default</th>
|
||||
<th class="head">choices</th>
|
||||
<th class="head">comments</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>pattern</td>
|
||||
<td>no</td>
|
||||
<td></td>
|
||||
<td><ul></ul></td>
|
||||
<td>If the service does not respond to the status command, name a substring to look for as would be found in the output of the <em>ps</em> command as a stand-in for a status result. If the string is found, the servie will be assumed to be running. (added in Ansible 0.7)</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>state</td>
|
||||
<td>no</td>
|
||||
<td></td>
|
||||
<td><ul><li>running</li><li>started</li><li>stopped</li><li>restarted</li><li>reloaded</li></ul></td>
|
||||
<td><em>started</em>, <em>stopped</em>, <em>reloaded</em>, <em>restarted</em>. <em>Started</em>/<em>stopped</em> are idempotent actions that will not run commands unless necessary. <em>restarted</em> will always bounce the service. <em>reloaded</em> will always reload.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>enabled</td>
|
||||
<td>no</td>
|
||||
<td></td>
|
||||
<td><ul><li>yes</li><li>no</li></ul></td>
|
||||
<td>Whether the service should start on boot.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>name</td>
|
||||
<td>yes</td>
|
||||
<td></td>
|
||||
<td><ul></ul></td>
|
||||
<td>Name of the service.</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
.. raw:: html
|
||||
|
||||
<p>Example action from Ansible Playbooks</p> <p><pre>
|
||||
service name=httpd state=started
|
||||
</pre></p>
|
||||
<p>Example action from Ansible Playbooks</p> <p><pre>
|
||||
service name=httpd state=stopped
|
||||
</pre></p>
|
||||
<p>Example action from Ansible Playbooks</p> <p><pre>
|
||||
service name=httpd state=restarted
|
||||
</pre></p>
|
||||
<p>Example action from Ansible Playbooks</p> <p><pre>
|
||||
service name=httpd state=reloaded
|
||||
</pre></p>
|
||||
<p>Example action from Ansible Playbooks</p> <p><pre>
|
||||
service name=foo pattern=/usr/bin/foo state=started
|
||||
</pre></p>
|
||||
<br/>
|
||||
|
||||
@ -0,0 +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.
|
||||
|
||||
|
||||
.. raw:: html
|
||||
|
||||
<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/>
|
||||
|
||||
.. raw:: html
|
||||
|
||||
<h4>Notes</h4>
|
||||
<p>More ansible facts will be added with successive releases. If <em>facter</em> or <em>ohai</em> are installed, variables from these programs will also be snapshotted into the JSON file for usage in templating. These variables are prefixed with <code>facter_</code> and <code>ohai_</code> 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 <em>facter</em> and <em>ohai</em> means you can avoid Ruby-dependencies on your remote systems.</p>
|
||||
|
||||
@ -0,0 +1,54 @@
|
||||
.. _shell:
|
||||
|
||||
shell
|
||||
``````````````````````````````
|
||||
|
||||
.. versionadded:: 0.2
|
||||
|
||||
The shell module takes the command name followed by a list of arguments, space delimited. It is almost exactly like the ``command`` module but runs the command through the user's configured shell on the remote node.
|
||||
|
||||
.. raw:: html
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<th class="head">parameter</th>
|
||||
<th class="head">required</th>
|
||||
<th class="head">default</th>
|
||||
<th class="head">choices</th>
|
||||
<th class="head">comments</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>creates</td>
|
||||
<td>no</td>
|
||||
<td></td>
|
||||
<td><ul></ul></td>
|
||||
<td>a filename, when it already exists, this step will NOT be run</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>chdir</td>
|
||||
<td>no</td>
|
||||
<td></td>
|
||||
<td><ul></ul></td>
|
||||
<td>cd into this directory before running the command (0.6 and later)</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>(free form)</td>
|
||||
<td>no</td>
|
||||
<td></td>
|
||||
<td><ul></ul></td>
|
||||
<td>The command module takes a free form command to run</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
.. raw:: html
|
||||
|
||||
<p>Execute the command in remote shell</p> <p><pre>
|
||||
shell somescript.sh >> somelog.txt
|
||||
</pre></p>
|
||||
<br/>
|
||||
|
||||
.. raw:: html
|
||||
|
||||
<h4>Notes</h4>
|
||||
<p>If you want to execute a command securely and predicably, it may be better to use the <span class='module'>command</span> module instead. Best practices when writing playbooks will follow the trend of using <span class='module'>command</span> unless <span class='module'>shell</span> is explicitly required. When running ad-hoc commands, use your best judgement.</p>
|
||||
|
||||
@ -0,0 +1,44 @@
|
||||
.. _slurp:
|
||||
|
||||
slurp
|
||||
``````````````````````````````
|
||||
|
||||
|
||||
This module works like ``fetch``. It is used for fetching a base64- encoded blob containing the data in a remote file.
|
||||
|
||||
.. raw:: html
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<th class="head">parameter</th>
|
||||
<th class="head">required</th>
|
||||
<th class="head">default</th>
|
||||
<th class="head">choices</th>
|
||||
<th class="head">comments</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>src</td>
|
||||
<td>yes</td>
|
||||
<td></td>
|
||||
<td><ul></ul></td>
|
||||
<td>The file on the remote system to fetch. This must be a file, not a directory.</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
.. raw:: html
|
||||
|
||||
<p>Example using <code>/usr/bin/ansible</code></p> <p><pre>
|
||||
ansible host -m slurp -a 'src=/tmp/xx'
|
||||
host | success >> {
|
||||
"content": "aGVsbG8gQW5zaWJsZSB3b3JsZAo=",
|
||||
"encoding": "base64"
|
||||
}
|
||||
|
||||
</pre></p>
|
||||
<br/>
|
||||
|
||||
.. raw:: html
|
||||
|
||||
<h4>Notes</h4>
|
||||
<p>See also: <span class='module'>fetch</span></p>
|
||||
|
||||
Some files were not shown because too many files have changed in this diff Show More
Loading…
Reference in New Issue