cmueller/ansible
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Add some docs/examples

Browse source 
Add a basic ansible-pull man page.

Add the example playbooks/scripts to the RPM package.

Closes #841
This commit is contained in:
Tim Bielawa 2012-08-14 10:46:16 -04:00
parent 7d50a5c2b7
commit 6d9e873724
9 changed files with 215 additions and 18 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
MANIFEST.in
View file

@ -1,6 +1,7 @@
include README.md packaging/rpm/ansible.spec COPYING
include examples/hosts
include examples/ansible.cfg
graft examples/playbooks
include packaging/distutils/setup.py
recursive-include docs *
recursive-include library *

2
Makefile
View file

@ -21,7 +21,7 @@ NAME = "ansible"
# directory of the target file ($@), kinda like `dirname`.
ASCII2MAN = a2x -D $(dir $@) -d manpage -f manpage $<
ASCII2HTMLMAN = a2x -D docs/html/man/ -d manpage -f xhtml
MANPAGES := docs/man/man1/ansible.1 docs/man/man1/ansible-playbook.1
MANPAGES := docs/man/man1/ansible.1 docs/man/man1/ansible-playbook.1 docs/man/man1/ansible-pull.1
SITELIB = $(shell python -c "from distutils.sysconfig import get_python_lib; print get_python_lib()")

37
docs/man/man1/ansible-playbook.1
View file

@ -1,13 +1,22 @@
'\" t
.\" Title: ansible-playbook
.\" Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
.\" Date: 08/06/2012
.\" Generator: DocBook XSL Stylesheets v1.76.1 <http://docbook.sf.net/>
.\" Date: 08/14/2012
.\" Manual: System administration commands
.\" Source: Ansible 0.7
.\" Language: English
.\"
.TH "ANSIBLE\-PLAYBOOK" "1" "08/06/2012" "Ansible 0\&.7" "System administration commands"
.TH "ANSIBLE\-PLAYBOOK" "1" "08/14/2012" "Ansible 0\&.7" "System administration commands"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
@ -36,7 +45,7 @@ The names of one or more YAML format files to run as ansible playbooks\&.
.sp
\fB\-v\fR, \fB\-\-verbose\fR
.sp
Verbose mode, more output from successful actions will be shown
Verbose mode, more output from successful actions will be shown\&.
.PP
\fB\-i\fR \fIPATH\fR, \fB\-\-inventory=\fR\fIPATH\fR
.RS 4
@ -73,7 +82,12 @@ Prompt for the SSH password instead of assuming key\-based authentication with s
.PP
\fB\-K\fR, \fB\-\-ask\-sudo\-pass\fR
.RS 4
Prompt for the password to use for playbook plays that request sudo access, if any
Prompt for the password to use for playbook plays that request sudo access, if any\&.
.RE
.PP
\fB\-U\fR, \fISUDO_USER\fR, \fB\-\-sudo\-user=\fR\fISUDO_USER\fR
.RS 4
Desired sudo user (default=root)\&.
.RE
.PP
\fB\-T\fR \fISECONDS\fR, \fB\-\-timeout=\fR\fISECONDS\fR
@ -91,6 +105,17 @@ Force all plays to use sudo, even if not marked as such\&.
.RS 4
Use this remote user name on playbook steps that do not indicate a user name to run as\&.
.RE
.PP
\fB\-c\fR \fICONNECTION\fR, \fB\-\-connection=\fR\fICONNECTION\fR
.RS 4
Connection type to use\&. Possible options are
\fIparamiko\fR
(SSH),
\fIssh\fR, and
\fIlocal\fR\&.
\fIlocal\fR
is mostly useful for crontab or kickstarts\&.
.RE
.SH "ENVIRONMENT"
.sp
The following environment variables may specified\&.
@ -108,6 +133,6 @@ Copyright \(co 2012, Michael DeHaan
Ansible is released under the terms of the GPLv3 License\&.
.SH "SEE ALSO"
.sp
\fBansible\fR(1)
\fBansible\fR(1), \fBansible\-pull\fR(1)
.sp
Extensive documentation as well as IRC and mailing list info is available on the ansible home page: https://ansible\&.github\&.com/

2
docs/man/man1/ansible-playbook.1.asciidoc.in
View file

@ -122,7 +122,7 @@ Ansible is released under the terms of the GPLv3 License.
SEE ALSO
--------
*ansible*(1)
*ansible*(1), *ansible-pull*(1)
Extensive documentation as well as IRC and mailing list info
is available on the ansible home page: <https://ansible.github.com/>

73
docs/man/man1/ansible-pull.1 Normal file
View file

@ -0,0 +1,73 @@
'\" t
.\" Title: ansible
.\" Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets v1.76.1 <http://docbook.sf.net/>
.\" Date: 08/14/2012
.\" Manual: System administration commands
.\" Source: Ansible 0.7
.\" Language: English
.\"
.TH "ANSIBLE" "1" "08/14/2012" "Ansible 0\&.7" "System administration commands"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
ansible-pull \- set up a remote copy of ansible on each managed node
.SH "SYNOPSIS"
.sp
ansible \-d DEST \-U URL [ \-C CHECKOUT ]
.SH "DESCRIPTION"
.sp
\fBAnsible\fR is an extra\-simple tool/framework/API for doing \*(Aqremote things\*(Aq over SSH\&.
.sp
Use ansible\-pull 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 inverts the default \fBpush\fR architecture of ansible into a \fBpull\fR architecture, which has near\-limitless scaling potential\&.
.sp
The setup playbook can be tuned to change the cron frequency, logging locations, and parameters to ansible\-pull\&.
.sp
This is useful both for extreme scale\-out as well as periodic remediation\&. Usage of the \fIfetch\fR module to retrieve logs from ansible\-pull runs would be an excellent way to gather and analyze remote logs from ansible\-pull\&.
.SH "OPTIONS"
.PP
\fB\-d\fR \fIDEST\fR, \fB\-\-directory=\fR\fIDEST\fR
.RS 4
Directory to checkout git repository into\&.
.RE
.PP
\fB\-U\fR \fIURL\fR, \fB\-\-url=\fR\fIURL\fR
.RS 4
URL of git repository to clone\&.
.RE
.PP
\fB\-C\fR \fICHECKOUT\fR, \fB\-\-checkout=\fR\fICHECKOUT\fR
.RS 4
Branch/Tag/Commit to checkout\&. Defaults to
\fIHEAD\fR\&.
.RE
.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\fR(1), \fBansible\-playbook\fR(1)
.sp
Extensive documentation as well as IRC and mailing list info is available on the ansible home page: https://ansible\&.github\&.com/

76
docs/man/man1/ansible-pull.1.asciidoc.in Normal file
View file

@ -0,0 +1,76 @@
ansible(1)
=========
:doctype:manpage
:man source: Ansible
:man version: %VERSION%
:man manual: System administration commands
NAME
----
ansible-pull - set up a remote copy of ansible on each managed node
SYNOPSIS
--------
ansible -d DEST -U URL [ -C CHECKOUT ]
DESCRIPTION
-----------
*Ansible* is an extra-simple tool/framework/API for doing \'remote things' over
SSH.
Use ansible-pull 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 inverts 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.
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.
OPTIONS
-------
*-d* 'DEST', *--directory=*'DEST'::
Directory to checkout git repository into.
*-U* 'URL', *--url=*'URL'::
URL of git repository to clone.
*-C* 'CHECKOUT', *--checkout=*'CHECKOUT'::
Branch/Tag/Commit to checkout. Defaults to 'HEAD'.
AUTHOR
------
Ansible was originally written by Michael DeHaan. See the AUTHORS file
for a complete list of contributors.
COPYRIGHT
---------
Copyright © 2012, Michael DeHaan
Ansible is released under the terms of the GPLv3 License.
SEE ALSO
--------
*ansible*(1), *ansible-playbook*(1)
Extensive documentation as well as IRC and mailing list info
is available on the ansible home page: <https://ansible.github.com/>

38
docs/man/man1/ansible.1
View file

@ -1,13 +1,22 @@
'\" t
.\" Title: ansible
.\" Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
.\" Date: 08/06/2012
.\" Generator: DocBook XSL Stylesheets v1.76.1 <http://docbook.sf.net/>
.\" Date: 08/14/2012
.\" Manual: System administration commands
.\" Source: Ansible 0.7
.\" Language: English
.\"
.TH "ANSIBLE" "1" "08/06/2012" "Ansible 0\&.7" "System administration commands"
.TH "ANSIBLE" "1" "08/14/2012" "Ansible 0\&.7" "System administration commands"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
@ -25,7 +34,7 @@ ansible \- run a command somewhere else
ansible <host\-pattern> [\-f forks] [\-m module_name] [\-a args]
.SH "DESCRIPTION"
.sp
\fBAnsible\fR is an extra\-simple tool/framework/API for doing \'remote things\' over SSH\&.
\fBAnsible\fR is an extra\-simple tool/framework/API for doing \*(Aqremote things\*(Aq over SSH\&.
.SH "ARGUMENTS"
.PP
\fBhost\-pattern\fR
@ -49,6 +58,11 @@ Level of parallelism\&.
is specified as an integer, the default is 5\&.
.RE
.PP
\fB\-\-private\-key=\fR\fIPRIVATE_KEY_FILE\fR
.RS 4
Use this file to authenticate the connection\&.
.RE
.PP
\fB\-m\fR \fINAME\fR, \fB\-\-module\-name=\fR\fINAME\fR
.RS 4
Execute the module called
@ -63,7 +77,7 @@ to load modules from\&. The default is
\fI/usr/share/ansible\fR\&.
.RE
.PP
\fB\-a\fR \'\fIARGUMENTS\fR\', \fB\-\-args=\fR\'\fIARGUMENTS\fR\'
\fB\-a\fR \*(Aq\fIARGUMENTS\fR\*(Aq, \fB\-\-args=\fR\*(Aq\fIARGUMENTS\fR\*(Aq
.RS 4
The
\fIARGUMENTS\fR
@ -131,12 +145,20 @@ Sudo to
instead of root\&. Implies \-\-sudo\&.
.RE
.PP
\fB\-\-private\-key=\fR\fIPRIVATE_KEY_FILE\fR
.RS 4
Use this file to authenticate the connection\&.
.RE
.PP
\fB\-c\fR \fICONNECTION\fR, \fB\-\-connection=\fR\fICONNECTION\fR
.RS 4
Connection type to use\&. Possible options are
\fIparamiko\fR
(SSH) and
\fIlocal\fR\&. Local is mostly useful for crontab or kickstarts\&.
(SSH),
\fIssh\fR, and
\fIlocal\fR\&.
\fIlocal\fR
is mostly useful for crontab or kickstarts\&.
.RE
.SH "INVENTORY"
.sp
@ -165,6 +187,6 @@ Copyright \(co 2012, Michael DeHaan
Ansible is released under the terms of the GPLv3 License\&.
.SH "SEE ALSO"
.sp
\fBansible\-playbook\fR(1)
\fBansible\-playbook\fR(1), \fBansible\-pull\fR(1)
.sp
Extensive documentation as well as IRC and mailing list info is available on the ansible home page: https://ansible\&.github\&.com/

2
docs/man/man1/ansible.1.asciidoc.in
View file

@ -160,7 +160,7 @@ Ansible is released under the terms of the GPLv3 License.
SEE ALSO
--------
*ansible-playbook*(1)
*ansible-playbook*(1), *ansible-pull*(1)
Extensive documentation as well as IRC and mailing list info
is available on the ansible home page: <https://ansible.github.com/>

2
packaging/rpm/ansible.spec
View file

@ -56,7 +56,7 @@ rm -rf $RPM_BUILD_ROOT
%config(noreplace) %{_sysconfdir}/ansible
%doc README.md PKG-INFO COPYING
%doc %{_mandir}/man1/ansible*
%doc examples/playbooks
%changelog
* Mon Aug 6 2012 Michael DeHaan <michael.dehaan@gmail.com> - 0.7-0