From 6d9e87372400f04594abf3c05b9d565cbc625db8 Mon Sep 17 00:00:00 2001 From: Tim Bielawa Date: Tue, 14 Aug 2012 10:46:16 -0400 Subject: [PATCH] Add some docs/examples Add a basic ansible-pull man page. Add the example playbooks/scripts to the RPM package. Closes #841 --- MANIFEST.in | 1 + Makefile | 2 +- docs/man/man1/ansible-playbook.1 | 37 ++++++++-- docs/man/man1/ansible-playbook.1.asciidoc.in | 2 +- docs/man/man1/ansible-pull.1 | 73 +++++++++++++++++++ docs/man/man1/ansible-pull.1.asciidoc.in | 76 ++++++++++++++++++++ docs/man/man1/ansible.1 | 38 +++++++--- docs/man/man1/ansible.1.asciidoc.in | 2 +- packaging/rpm/ansible.spec | 2 +- 9 files changed, 215 insertions(+), 18 deletions(-) create mode 100644 docs/man/man1/ansible-pull.1 create mode 100644 docs/man/man1/ansible-pull.1.asciidoc.in diff --git a/MANIFEST.in b/MANIFEST.in index 15d0a74b3c4..cd7d324d705 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -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 * diff --git a/Makefile b/Makefile index f9b2418b51b..5aab771cdc7 100644 --- a/Makefile +++ b/Makefile @@ -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()") diff --git a/docs/man/man1/ansible-playbook.1 b/docs/man/man1/ansible-playbook.1 index 6372a4a2764..06c10170a1a 100644 --- a/docs/man/man1/ansible-playbook.1 +++ b/docs/man/man1/ansible-playbook.1 @@ -1,13 +1,22 @@ '\" t .\" Title: ansible-playbook .\" Author: [see the "AUTHOR" section] -.\" Generator: DocBook XSL Stylesheets v1.75.2 -.\" Date: 08/06/2012 +.\" Generator: DocBook XSL Stylesheets v1.76.1 +.\" 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/ diff --git a/docs/man/man1/ansible-playbook.1.asciidoc.in b/docs/man/man1/ansible-playbook.1.asciidoc.in index a1aff4e2f6e..114100bbde4 100644 --- a/docs/man/man1/ansible-playbook.1.asciidoc.in +++ b/docs/man/man1/ansible-playbook.1.asciidoc.in @@ -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: diff --git a/docs/man/man1/ansible-pull.1 b/docs/man/man1/ansible-pull.1 new file mode 100644 index 00000000000..5eea65bede7 --- /dev/null +++ b/docs/man/man1/ansible-pull.1 @@ -0,0 +1,73 @@ +'\" t +.\" Title: ansible +.\" Author: [see the "AUTHOR" section] +.\" Generator: DocBook XSL Stylesheets v1.76.1 +.\" 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/ diff --git a/docs/man/man1/ansible-pull.1.asciidoc.in b/docs/man/man1/ansible-pull.1.asciidoc.in new file mode 100644 index 00000000000..5bf63e850ec --- /dev/null +++ b/docs/man/man1/ansible-pull.1.asciidoc.in @@ -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: diff --git a/docs/man/man1/ansible.1 b/docs/man/man1/ansible.1 index 358129a09e2..bcebfff36b2 100644 --- a/docs/man/man1/ansible.1 +++ b/docs/man/man1/ansible.1 @@ -1,13 +1,22 @@ '\" t .\" Title: ansible .\" Author: [see the "AUTHOR" section] -.\" Generator: DocBook XSL Stylesheets v1.75.2 -.\" Date: 08/06/2012 +.\" Generator: DocBook XSL Stylesheets v1.76.1 +.\" 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 [\-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/ diff --git a/docs/man/man1/ansible.1.asciidoc.in b/docs/man/man1/ansible.1.asciidoc.in index 62a61815506..d3f0dcda95d 100644 --- a/docs/man/man1/ansible.1.asciidoc.in +++ b/docs/man/man1/ansible.1.asciidoc.in @@ -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: diff --git a/packaging/rpm/ansible.spec b/packaging/rpm/ansible.spec index 5dfd25b4953..c28aa066c6c 100644 --- a/packaging/rpm/ansible.spec +++ b/packaging/rpm/ansible.spec @@ -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 - 0.7-0