Skip to content

A
ansible
Commit 55d256d8 by Michael DeHaan
Options

Added solution to avoid checking in manpages. Just run "make" and we'll build 

docs before python setup.py.   Seems reasonable to let Makefile drive
parent 19fdb730
Showing with 10 additions and 341 deletions
Makefile
......@@ -5,6 +5,8 @@ ASCII2HTMLMAN = a2x -D docs/html/man/ -d manpage -f xhtml
MANPAGES := docs/man/man1/ansible.1 docs/man/man5/ansible-modules.5 docs/man/man5/ansible-playbook.5
SITELIB = $(shell python -c "from distutils.sysconfig import get_python_lib; print get_python_lib()")
all: clean python
docs: manuals
manuals: $(MANPAGES)
......@@ -28,5 +30,13 @@ clean:
find ./docs/ -type f -name "*.xml" -delete
find . -type f -name "#*" -delete
python: docs
python setup.py build
install: docs
python setup.py install
.PHONEY: docs manual clean pep8
vpath %.asciidoc docs/man/man1
docs/man/man1/ansible.1 deleted 100644 → 0
'\" t
.\" Title: ansible
.\" Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
.\" Date: 02/28/2012
.\" Manual: System administration commands
.\" Source: Ansible 0.0.1
.\" Language: English
.\"
.TH "ANSIBLE" "1" "02/28/2012" "Ansible 0\&.0\&.1" "System administration commands"
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
ansible \- run a command somewhere else
.SH "SYNOPSIS"
.sp
ansible [\-f forks] [\-p pattern ] [\-u remote_user] [\-n module_name] [\-a [args1 [args2 \&...]]]
.SH "DESCRIPTION"
.sp
\fBAnsible\fR is an extra\-simple tool/framework/API for doing \'remote things\' over SSH\&.
.SH "OPTIONS"
.PP
\fB\-k\fR, \fB\-\-ask\-pass\fR
.RS 4
Ask the user to input the ssh password for connecting\&. Generally using ssh\-agent instead is preferred\&.
.RE
.PP
\fB\-l\fR, \fB\-\-host\-list\fR
.RS 4
Path to hosts list, which defaults to /etc/ansible/hosts\&. Users can use multiple files to emulate groups of systems\&.
.RE
.PP
\fB\-m\fR, \fB\-\-module\-path\fR
.RS 4
Override the path to module library, which defaults to /usr/share/ansible\&. The module library contains runnable modules that do
\fIthings\fR
to remote hosts\&. See ansible\-modules(5) for a list of those that bundled with Ansible\&.
.RE
.PP
\fB\-f\fR, \fB\-\-forks\fR
.RS 4
Level of parallelism\&. Specify as an integer, the default is 3\&. If set to "1" debugging for certain classes of internal errors may become easier\&.
.RE
.PP
\fB\-n\fR, \fB\-\-name\fR
.RS 4
Module name to execute\&.
.RE
.PP
\fB\-a\fR, \fB\-\-args\fR
.RS 4
Arguments to module, as a single string\&. Be sure to observe proper shell quoting rules\&. How these are handled are up to the module, but most modules take "key=value" pairs delimited by spaces\&.
.RE
.PP
\fB\-p\fR, \fB\-\-pattern\fR
.RS 4
Hostname pattern\&. Accepts shell\-like globs which can be seperated with ";" The default is "*" which matches all hosts in the ansible hosts file\&.
.RE
.PP
\fB\-u\fR, \fB\-\-remote\-user\fR
.RS 4
Remote user to connect as\&. Uses
\fIroot\fR
by default\&.
.RE
.SH "INVENTORY"
.sp
Ansible stores the hosts it can potentially operate on in an inventory file\&. The syntax is simple: one host per line\&. Organize your hosts into multiple groups by separating them into multiple inventory files\&.
.SH "FILES"
.sp
/etc/ansible/hosts \(em Default hosts file
.sp
/usr/share/ansible \(em Default module library
.SH "AUTHOR"
.sp
Ansible was originally written by Michael DeHaan\&. See the AUTHORS file for a complete list of contributors\&.
.SH "COPYRIGHT"
.sp
Copyright \(co 2012, Michael DeHaan
.sp
Ansible is released under the terms of the GPLv3 License\&.
.SH "SEE ALSO"
.sp
\fBansible\-modules\fR(5),
.sp
\fBansible\-playbook\fR(5),
.sp
Ansible home page: https://github\&.com/mpdehaan/ansible/
docs/man/man5/ansible-modules.5 deleted 100644 → 0
'\" t
.\" Title: ansible-modules
.\" Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
.\" Date: 02/27/2012
.\" Manual: System administration commands
.\" Source: Ansible-modules 0.0.1
.\" Language: English
.\"
.TH "ANSIBLE\-MODULES" "5" "02/27/2012" "Ansible\-modules 0\&.0\&.1" "System administration commands"
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
ansible-modules \- stock modules shipped with ansible
.SH "DESCRIPTION"
.sp
Ansible ships with a number of modules that can be executed directly on remote hosts or through ansible playbooks\&.
.SH "IDEMPOTENCE"
.sp
Most modules other than command are idempotent, meaning they will seek to avoid changes unless a change needs to be made\&. When using ansible playbooks, these modules can trigger change events, as described in ansible\-playbooks (5)\&.
.sp
Unless otherwise noted, all modules support change hooks\&.
.SH "COMMAND"
.sp
The command module takes the command name followed by a list of arguments, space delimited\&. This is the only module that does not use key=value style parameters\&.
.PP
Example usage
.RS 4
/sbin/shutdown \-t now
.RE
.sp
This module does not support change hooks\&.
.sp
Returns the return code from the program as well as timing information\&.
.sp
(Async command running and command execution time limits are in plan\&.)
.SH "COPY"
.sp
The copy module moves a file on the local box to remote locations\&.
.PP
\fBsrc=\fR
.RS 4
Local absolute path to a file to copy to the remote server
.RE
.PP
\fBdest=\fR
.RS 4
Remote absolute path where the file should end up
.RE
.sp
This module also returns md5sum information about the resultant file\&.
.SH "FACTER"
.sp
Runs the discovery program \fIfacter\fR on the remote system, returning JSON data that can be useful for inventory purposes\&.
.sp
Requires that \fIfacter\fR and \fIruby\-json\fR be installed on the remote end\&.
.sp
This module is informative only \- it takes no parameters & does not support change hooks, nor does it make any changes on the system\&.
.SH "FILE"
.sp
Ensures the ownership and permissions of files are as desired\&.
.sp
Use copy or template first if you need to make sure a file is on the box\&.
.sp
In plan\&.
.SH "GIT"
.sp
Deploys software from git checkouts\&.
.PP
\fBrepo=\fR
.RS 4
git or http protocol address of the repo to checkout
.RE
.PP
\fBdest=\fR
.RS 4
where to check it out, an absolute directory path
.RE
.PP
\fBversion=\fR
.RS 4
what version to check out \(em either the git SHA, the literal string
\fIHEAD\fR, or a tag name
.RE
.SH "OHAI"
.sp
Similar to the facter module, this returns JSON inventory data\&. Ohai data is a bit more verbose and nested than facter\&.
.sp
Requires that \fIohai\fR be installed on the remote end\&.
.sp
This module is information only \- it takes no parameters & does not support change hooks, nor does it make any changes on the system\&.
.SH "PING"
.sp
A trivial test module, this module always returns the integer \fI1\fR on successful contact\&.
.sp
This module does not support change hooks\&.
.sp
This module is informative only \- it takes no parameters & does not support change hooks, nor does it make any changes on the system\&.
.SH "SERVICE"
.sp
Controls services on remote machines\&.
.PP
\fBstate=\fR
.RS 4
Values are
\fIstarted\fR,
\fIstopped\fR, or
\fIrestarted\fR\&. Started/stopped are idempotent actions that will not run commands unless neccessary\&.
\fIrestarted\fR
will always bounce the service
.RE
.PP
\fBname=\fR
.RS 4
The name of the service
.RE
.SH "SETUP"
.sp
Writes a JSON file containing key/value data, for use in templating\&. Call this once before using the template modules, usually as the very first step in your playbook\&.
.sp
If facter or ohai are installed, variables from these programs will also be snapshotted into the JSON file for usage in templating\&. These variables are prefixed with \fIfacter_\fR and \'ohai_" so it\(cqs easy to tell their source\&.
.PP
\fBmetadata=\fR
.RS 4
Optionally overrides the default JSON file location of /etc/ansible/setup\&. If used, also supply the metadata parameter to
\fItemplate\fR\&. Change if running as a non\-root remote user who does not have permissions on /etc/ansible\&.
.RE
.PP
\fBanything=\fR
.RS 4
any other parameters can be named basically anything, and set a key=value pair in the JSON file for use in templating\&.
.RE
.SH "TEMPLATE"
.sp
Templates a file out to a remote server\&. Call the setup module prior to usage\&.
.PP
\fBsrc=\fR
.RS 4
path of a Jinja2 formatted template on the local server
.RE
.PP
\fBdest\fR
.RS 4
location to render the template on the remote server
.RE
.PP
\fBmetadata\fR
.RS 4
location of a JSON file to use to supply template data\&. Default is /etc/ansible/setup which is the same as the default for the setup module\&. Change if running as a non\-root remote user who does not have permissions on /etc/ansible\&.
.RE
.sp
This module also returns md5sum information about the resultant file\&.
.SH "USER"
.sp
This module is in plan\&.
.SH "YUM"
.sp
This module is in plan\&.
.SH "WRITING YOUR OWN MODULES"
.sp
To write your own modules, simply follow the convention of those already available in /usr/share/ansible\&. Modules must return JSON but can be written in any language\&. To support change hooks, modules should return hashes, with a changed: True/False element at the top level\&. Modules can also choose to indicate a failure scenario by returning a top level \fIfailure\fR element with a True value\&.
.SH "AUTHOR"
.sp
Ansible was originally written by Michael DeHaan\&. See the AUTHORS file for a complete list of contributors\&.
.SH "SEE ALSO"
.sp
\fBansible\fR(1)
.sp
\fBansible\-playbook\fR(5)
.sp
Ansible home page: https://github\&.com/mpdehaan/ansible/
docs/man/man5/ansible-playbook.5 deleted 100644 → 0
'\" t
.\" Title: ansible-modules
.\" Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
.\" Date: 02/28/2012
.\" Manual: System administration commands
.\" Source: Ansible-playbook 0.0.1
.\" Language: English
.\"
.TH "ANSIBLE\-MODULES" "5" "02/28/2012" "Ansible\-playbook 0\&.0\&.1" "System administration commands"
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
ansible-playbook \- format and function of an ansible playbook file
.SH "DESCRIPTION"
.sp
Ansible ships with \fIansible\-playbook\fR, a tool for running playbooks\&. Playbooks can represent frequent tasks, desired system configurations, or deployment processes\&.
.SH "FORMAT"
.sp
Playbooks are written in YAML\&.
.SH "EXAMPLE"
.sp
see https://github\&.com/mpdehaan/ansible/blob/master/examples/playbook\&.yml
.SH "WHAT THE EXAMPLE MEANS"
.sp
Here\(cqs what the above example will do\&.
.sp
For all hosts in /etc/ansible/hosts (one host per line) that are named \fIwebserver\-anything\fR, first write a JSON file into /etc/ansible/setup on each remote system with the values max_clients and http_port\&.
.sp
Next, use a Jinja2 template locally residing at /srv/templates/httpd\&.j2 to write the Apache config file on each host to the path /etc/httpd\&.conf, using the previous values\&.
.sp
We\(cqll ensure that apache is running if stopped\&.
.sp
If and only if the config file changed, note that we need to restart apache at the end of the run, otherwise, don\(cqt bother because we already know it is running\&.
.SH "HIGH LEVEL EXPLANATION"
.sp
Playbooks are executed top down and can contain multiple references to patterns\&. For instance, a playbook could do something to all webservers, then do something to all database servers, then do something different to all webservers again\&.
.sp
For each pattern, the tasks in the \fItasks\fR list are executed in order for all hosts in the host file matching the pattern\&.
.sp
For each task, a name/action pair describes what the task is and what ansible module to use to accomplish the task, along with any arguments\&. Additional fields like \fIcomment:\fR can be added and will be ignored, so feel free to take notes in the file\&.
.sp
Most modules accept key=value format arguments\&.
.sp
Handlers are like tasks, but are conditionally executed\&. If a module reports a \fIchange\fR, it can notify one or more handler by name\&. If notified, it will run only for hosts that changed\&.
.SH "ERROR HANDLING"
.sp
If a host has a failure, the host will be ignored for the remainder of the playbook execution\&.
.SH "AUTHOR"
.sp
Ansible was originally written by Michael DeHaan\&. See the AUTHORS file for a complete list of contributors\&.
.SH "SEE ALSO"
.sp
\fBansible\fR(1)
.sp
\fBansible\-playbook\fR(5) \- pending
.sp
Ansible home page: https://github\&.com/mpdehaan/ansible/
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment