mirror of
https://github.com/ansible-collections/community.general.git
synced 2024-09-14 20:13:21 +02:00
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
This commit is contained in:
Michael DeHaan
parent
19fdb7305d
commit
55d256d82a
4 changed files with 10 additions and 341 deletions
10
Makefile
10
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
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -1,96 +0,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/
|
||||
|
|
@ -1,179 +0,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/
|
||||
|
|
@ -1,66 +0,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/
|
||||
Loading…
Reference in a new issue