ansible/community.general
1
0
Fork 0
mirror of https://github.com/ansible-collections/community.general.git synced 2024-09-14 20:13:21 +02:00
Code Releases Activity

added docs to CLI docstringsadded

Browse source 
removed 'now intermediate build files' from repo
adjusted gitignore
This commit is contained in:
Brian Coca 2017-03-23 01:11:40 -04:00 committed by Brian Coca
parent 424e1946f4
commit 18a7a1ec31
21 changed files with 269 additions and 1803 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

9
.gitignore vendored
View file

@ -19,12 +19,8 @@ rpm-build
# Mac OS X stuff...
.DS_Store
# manpage build stuff...
docs/man/man1/ansible.1
docs/man/man1/ansible-doc.1
docs/man/man1/ansible-galaxy.1
docs/man/man1/ansible-playbook.1
docs/man/man1/ansible-pull.1
docs/man/man1/ansible-vault.1
docs/man/man1/ansible*.1
docs/man/man1/ansible*.1.asciidoc.in
docs/man/man3/*
# Sublime stuff
*.sublime-project
@ -32,6 +28,7 @@ docs/man/man3/*
# docsite stuff...
docs/docsite/rst/modules_by_category.rst
docs/docsite/rst/playbooks_directives.rst
docs/docsite/rst/playbook_keywords.rst
docs/docsite/rst/list_of_*.rst
docs/docsite/rst/*_module.rst
docs/docsite/*.html

13
Makefile
View file

@ -21,7 +21,8 @@ OS = $(shell uname -s)
# Manpages are currently built with asciidoc -- would like to move to markdown
# This doesn't evaluate until it's called. The -D argument is the
# directory of the target file ($@), kinda like `dirname`.
MANPAGES := docs/man/man1/ansible.1 docs/man/man1/ansible-playbook.1 docs/man/man1/ansible-pull.1 docs/man/man1/ansible-doc.1 docs/man/man1/ansible-galaxy.1
MANPAGES := ./docs/man/man1/ansible*.1
ifneq ($(shell which a2x 2>/dev/null),)
ASCII2MAN = a2x -L -D $(dir $@) -d manpage -f manpage $<
ASCII2HTMLMAN = a2x -L -D docs/html/man/ -d manpage -f xhtml
@ -160,7 +161,7 @@ clean:
find ./docs/man -type f -name "*.xml" -delete
find ./docs/man -type f -name "*.asciidoc" -delete
find ./docs/man/man3 -type f -name "*.3" -delete
find ./docs/man/man1 -type f -name "*.1" -delete
rm -f ./docs/man/man1/*
@echo "Cleaning up output from test runs"
rm -rf test/test_data
@echo "Cleaning up RPM building stuff"
@ -191,7 +192,7 @@ sdist: clean docs
sdist_upload: clean docs
$(PYTHON) setup.py sdist upload 2>&1 |tee upload.log
rpmcommon: $(MANPAGES) sdist
rpmcommon: docs sdist
@mkdir -p rpm-build
@cp dist/*.gz rpm-build/
@sed -e 's#^Version:.*#Version: $(VERSION)#' -e 's#^Release:.*#Release: $(RPMRELEASE)%{?dist}#' $(RPMSPEC) >rpm-build/$(NAME).spec
@ -301,6 +302,10 @@ deb-src-upload: deb-src
webdocs:
(cd docs/docsite/; CPUS=$(CPUS) make docs)
docs: $(MANPAGES)
docs: lib/ansible/cli/*.py
mkdir -p ./docs/man/man1/
PYTHONPATH=./lib ./docs/bin/generate_man.py
make $(MANPAGES)
alldocs: docs webdocs

126
docs/bin/generate_man.py Executable file
View file

@ -0,0 +1,126 @@
#!/usr/bin/env python
import os
import io
import sys
from jinja2 import Environment, FileSystemLoader
def get_options(optlist):
''' get actual options '''
opts = []
for opt in optlist:
res = {
'desc': opt.help,
'options': opt._short_opts + opt._long_opts
}
if opt.action == 'store':
res['arg'] = opt.dest.upper()
opts.append(res)
return opts
def opt_doc_list(cli):
''' iterate over options lists '''
results = []
for optg in cli.parser.option_groups:
results.extend(get_options(optg.option_list))
results.extend(get_options(cli.parser.option_list))
return results
def opts_docs(cli, name):
''' generate doc structure from options '''
# cli name
if '-' in name:
name = name.split('-')[1]
else:
name = 'adhoc'
# cli info
docs = {
'cli': name,
'usage': cli.parser.usage,
'short_desc': cli.parser.description,
'long_desc': cli.__doc__,
}
# force populate parser with per action options
if cli.VALID_ACTIONS:
docs['actions'] = {}
# avoid dupe errors
cli.parser.set_conflict_handler('resolve')
for action in cli.VALID_ACTIONS:
cli.args.append(action)
cli.set_action()
docs['actions'][action] = getattr(cli, 'execute_%s' % action).__doc__
docs['options'] = opt_doc_list(cli)
return docs
if __name__ == '__main__':
template_file = 'man.j2'
# need to be in right dir
os.chdir(os.path.dirname(__file__))
allvars = {}
output = {}
cli_list = []
for binary in os.listdir('../../lib/ansible/cli'):
if not binary.endswith('.py'):
continue
elif binary == '__init__.py':
continue
libname = os.path.splitext(binary)[0]
print("Found CLI %s" % libname)
if libname == 'adhoc':
myclass = 'AdHocCLI'
output[libname] = 'ansible.1.asciidoc.in'
else:
myclass = "%sCLI" % libname.capitalize()
output[libname] = 'ansible-%s.1.asciidoc.in' % libname
# instanciate each cli and ask its options
mycli = getattr(__import__("ansible.cli.%s" % libname, fromlist=[myclass]), myclass)
cli_object = mycli([])
try:
cli_object.parse()
except:
# no options passed, we expect errors
pass
allvars[libname] = opts_docs(cli_object, libname)
for extras in ('ARGUMENTS'):
if hasattr(cli_object, extras):
allvars[libname][extras.lower()] = getattr(cli_object, extras)
cli_list = allvars.keys()
for libname in cli_list:
# template it!
env = Environment(loader=FileSystemLoader('../templates'))
template = env.get_template('man.j2')
# add rest to vars
tvars = allvars[libname]
tvars['cli_list'] = cli_list
tvars['cli'] = libname
if '-i' in tvars['options']:
print('uses inventory')
manpage = template.render(tvars)
filename = '../man/man1/%s' % output[libname]
with io.open(filename, 'w') as f:
f.write(manpage)
print("Wrote man docs to %s" % filename)

261
docs/man/man1/ansible-console.1.asciidoc.in
View file

@ -1,261 +0,0 @@
ansible-console(1)
==================
:doctype:manpage
3:man source: Ansible
:man version: %VERSION%
:man manual: System administration commands
NAME
----
ansible-console - a REPL for ad-hoc ansible tasks
SYNOPSIS
--------
ansible-console [-m module_name] [-a args] [options] [host-pattern]
DESCRIPTION
-----------
*Ansible console* is a REPL that allows for running ad-hoc tasks against
a chosen inventory (based on dominis' ansible-shell).
ARGUMENTS
---------
*host-pattern*::
A name of a group in the inventory, a shell-like glob selecting
hosts in inventory or any combination of the two separated by commas.
OPTIONS
-------
*-a* \'_ARGUMENTS_', *--args=*\'_ARGUMENTS_'::
The 'ARGUMENTS' to pass to the module.
*-b*, *--become*::
Use privilege escalation (specific one depends on become_method),
this does not imply prompting for passwords.
*K*, *--ask-become-pass*::
Ask for privilege escalation password.
*-k*, *--ask-pass*::
Prompt for the connection password, if it is needed for the transport used.
For example, using ssh and not having a key-based authentication with ssh-agent.
*--ask-su-pass*::
Prompt for su password, used with --su (deprecated, use become).
*--ask-sudo-pass*::
Prompt for the password to use with --sudo, if any (deprecated, use become).
*--ask-vault-pass*::
Prompt for vault password.
*-B* 'NUM', *--background=*'NUM'::
Run commands in the background, killing the task after 'NUM' seconds.
*--become-method=*'BECOME_METHOD'::
Privilege escalation method to use (default=sudo),
valid choices: [ sudo | su | pbrun | pfexec | runas | doas | dzdo ]
*--become-user=*'BECOME_USER'::
Run operations as this user (default=root).
*-C*, *--check*::
Do not make any changes on the remote system, but test resources to see what might
have changed. Note this can not scan all possible resource types and is only
a simulation.
*-c* 'CONNECTION', *--connection=*'CONNECTION'::
Connection type to use. Most common options are 'paramiko' (SSH), 'ssh', 'winrm'
and 'local'. 'local' is mostly useful for crontab or kickstarts.
*-e* 'EXTRA_VARS, *--extra-vars=*'EXTRA_VARS'::
Extra variables to inject into a playbook, in key=value key=value format or
as quoted YAML/JSON (hashes and arrays). To load variables from a file, specify
the file preceded by @ (e.g. @vars.yml).
*-f* 'NUM', *--forks=*'NUM'::
Level of parallelism. 'NUM' is specified as an integer, the default is 5.
*-h*, *--help*::
Show help message and exit.
*-i* 'PATH', *--inventory=*'PATH'::
The 'PATH' to the inventory, which defaults to '/etc/ansible/hosts'.
Alternatively you can use a comma separated list of hosts or single host with traling comma 'host,'.
*-l* 'SUBSET', *--limit=*'SUBSET'::
Further limits the selected host/group patterns.
You can prefix it with '~' to indicate that the pattern is a regex.
*--list-hosts*::
Outputs a list of matching hosts; does not execute anything else.
*-m* 'NAME', *--module-name=*'NAME'::
Execute the module called 'NAME'.
*-M* 'DIRECTORY', *--module-path=*'DIRECTORY'::
The 'DIRECTORY' search path to load modules from. The default is
'/usr/share/ansible'. This can also be set with the ANSIBLE_LIBRARY
environment variable.
*-o*, *--one-line*::
Try to output everything on one line.
*-P* 'NUM', *--poll=*'NUM'::
Poll a background job every 'NUM' seconds. Requires *-B*.
*--private-key=*'PRIVATE_KEY_FILE'::
Use this file to authenticate the connection.
*-S*, *--su*::
Run operations with su (deprecated, use become).
*-R* 'SU_USER', *--se-user=*'SUDO_USER'::
Run operations with su as this user (default=root) (deprecated, use become).
*-s*, *--sudo*::
Run the command as the user given by -u and sudo to root (deprecated, use become).
*--ssh-common-args=*''-o ProxyCommand="ssh -W %h:%p ..." ...''::
Add the specified arguments to any sftp/scp/ssh command-line. Useful to
set a ProxyCommand to use a jump host, but any arguments that are
accepted by all three programs may be specified.
*--sftp-extra-args=*''-f ...''::
Add the specified arguments to any sftp command-line.
*--scp-extra-args=*''-l ...''::
Add the specified arguments to any scp command-line.
*--ssh-extra-args=*''-R ...''::
Add the specified arguments to any ssh command-line.
*-U* 'SUDO_USERNAME', *--sudo-user=*'SUDO_USERNAME'::
Sudo to 'SUDO_USERNAME' default is root. (deprecated, use become).
*-t* 'DIRECTORY', *--tree=*'DIRECTORY'::
Save contents in this output 'DIRECTORY', with the results saved in a
file named after each host.
*-T* 'SECONDS', *--timeout=*'SECONDS'::
Connection timeout to use when trying to talk to hosts, in 'SECONDS'.
*-u* 'USERNAME', *--user=*'USERNAME'::
Use this 'USERNAME' to login to the target host, instead of the current user.
*--vault-password-file=*'VAULT_PASSWORD_FILE'::
A file containing the vault password to be used during the decryption of vault encrypted files.
Be sure to keep this file secured if it is used. If the file is executable,
it will be run and its standard output will be used as the password.
*-v*, *--verbose*::
Verbose mode, more output from successful actions will be shown.
Give up to three times for more output.
*--version*::
Show program version number and exit.
INVENTORY
---------
Ansible stores the hosts it can potentially operate on in an inventory.
This can be an ini-like file, a script, directory or a list.
The ini syntax is one host per line. Groups headers are allowed and
are included on their own line, enclosed in square brackets that start the line.
Ranges of hosts are also supported. For more information and
additional options, see the documentation on http://docs.ansible.com/.
ENVIRONMENT
-----------
The following environment variables may be specified.
ANSIBLE_INVENTORY -- Override the default ansible inventory file
ANSIBLE_LIBRARY -- Override the default ansible module library path
ANSIBLE_CONFIG -- Override the default ansible config file
Many more are available for most options in ansible.cfg
FILES
-----
/etc/ansible/hosts -- Default inventory file
/usr/share/ansible/ -- Default module library
/etc/ansible/ansible.cfg -- Config file, used if present
~/.ansible.cfg -- User config file, overrides the default config if present
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-playbook*(1), *ansible-pull*(1), *ansible-doc*(1), *ansible-vault*(1), *ansible-galaxy*(1)
Extensive documentation is available in the documentation site:
<http://docs.ansible.com>. IRC and mailing list info can be found
in file CONTRIBUTING.md, available in: <https://github.com/ansible/ansible>

91
docs/man/man1/ansible-doc.1.asciidoc.in
View file

@ -1,91 +0,0 @@
ansible-doc(1)
==============
:doctype: manpage
:man source: Ansible
:man version: %VERSION%
:man manual: System administration commands
NAME
----
ansible-doc - show documentation on Ansible plugins
SYNOPSIS
--------
ansible-doc [-M plugin_path] [-l] [-s] [-t <type>] [plugin...]
DESCRIPTION
-----------
*ansible-doc* displays information on modules installed in Ansible
libraries. It displays a terse listing of plugins and their short
descriptions, provides a printout of their DOCUMENTATION strings,
and it can create a short "snippet" which can be pasted into a
playbook.
OPTIONS
-------
*-M* 'DIRECTORY', *--plugin-path=*'DIRECTORY'::
The 'DIRECTORY' search path to load plugins from.
If not specified Ansbile uses it's normal search path and configuration.
*-s*, *--snippet=*::
Produce a snippet which can be copied into a playbook for modification, like a kind of task template.
*-l*, *--list=*::
Produce a terse listing of plugins and a short description of each.
*-t*, *--type=*::
Specify the type of plugin to target, default is 'module'.
Other choices are 'cache', 'callback', 'connection', 'lookup' and 'strategy'.
ENVIRONMENT
-----------
ANSIBLE_CONFIG -- Configuration file to use
ANSIBLE_LIBRARY -- Override the default ansible module library path
ANSIBLE_CACHE_PLUGINS -- Override the default ansible cache plugin path
ANSIBLE_CALLBACK_PLUGINS -- Override the default ansible callback plugin path
ANSIBLE_CONNECTION_PLUGINS -- Override the default ansible connection plugin path
ANSIBLE_LOOKUP_PLUGINS -- Override the default ansible lookup plugin path
ANSIBLE_STRATEGY_PLUGINS -- Override the default ansible strategy plugin path
FILES
-----
/etc/ansible/ansible.cfg -- Config file, used if present
~/.ansible.cfg -- User config file, overrides the default config if present
AUTHOR
------
ansible-doc was originally written by Jan-Piet Mens. See the AUTHORS file for a complete list of contributors.
COPYRIGHT
---------
Copyright © 2012, Jan-Piet Mens
Ansible is released under the terms of the GPLv3 License.
SEE ALSO
--------
*ansible-playbook*(1), *ansible*(1), *ansible-pull*(1), *ansible-vault*(1), *ansible-galaxy*(1)
Extensive documentation is available in the documentation site:
<http://docs.ansible.com>. IRC and mailing list info can be found
in file CONTRIBUTING.md, available in: <https://github.com/ansible/ansible>

384
docs/man/man1/ansible-galaxy.1.asciidoc.in
View file

@ -1,384 +0,0 @@
ansible-galaxy(1)
===================
:doctype: manpage
:man source: Ansible
:man version: %VERSION%
:man manual: System administration commands
NAME
----
ansible-galaxy - manage roles using galaxy.ansible.com
SYNOPSIS
--------
ansible-galaxy [delete|import|info|init|install|list|login|remove|search|setup] [--help] [options] ...
DESCRIPTION
-----------
*Ansible Galaxy* is a shared repository for Ansible roles.
The ansible-galaxy command can be used to manage these roles,
or for creating a skeleton framework for roles you'd like to upload to Galaxy.
COMMON OPTIONS
--------------
*-h*, *--help*::
Show a help message related to the given sub-command.
INSTALL
-------
The *install* sub-command is used to install roles.
USAGE
~~~~~
$ ansible-galaxy install [options] [-r FILE | role_name(s)[,version] | tar_file(s)]
Roles can be installed in several different ways:
* A username.rolename[,version] - this will install a single role. The Galaxy
API will be contacted to provide the information about the role, and the
corresponding .tar.gz will be downloaded from *github.com*. If the version
is omitted, the most recent version available will be installed.
* A file name, using *-r* - this will install multiple roles listed one per
line. The format of each line is the same as above: username.rolename[,version]
* A .tar.gz of a valid role you've downloaded directly from *github.com*. This
is mainly useful when the system running Ansible does not have access to
the Galaxy API, for instance when behind a firewall or proxy.
OPTIONS
~~~~~~~
*-f*, *--force*::
Force overwriting an existing role.
*-i*, *--ignore-errors*::
Ignore errors and continue with the next specified role.
*-n*, *--no-deps*::
Don't download roles listed as dependencies.
*-p* 'ROLES_PATH', *--roles-path=*'ROLES_PATH'::
The path to the directory containing your roles. The default is the *roles_path*
configured in your *ansible.cfg* file (/etc/ansible/roles if not configured)
*-r* 'ROLE_FILE', *--role-file=*'ROLE_FILE'::
A file containing a list of roles to be imported, as specified above. This
option cannot be used if a rolename or .tar.gz have been specified.
REMOVE
------
The *remove* sub-command is used to remove one or more roles.
USAGE
~~~~~
$ ansible-galaxy remove role1 role2 ...
OPTIONS
~~~~~~~
*-p* 'ROLES_PATH', *--roles-path=*'ROLES_PATH'::
The path to the directory containing your roles. The default is the *roles_path*
configured in your *ansible.cfg* file (/etc/ansible/roles if not configured)
INIT
----
The *init* command is used to create a new role suitable for uploading
to https://galaxy.ansible.com (or for roles in general). Creates a skeleton
directory structure and default files.
USAGE
~~~~~
$ ansible-galaxy init [options] role_name
OPTIONS
~~~~~~~
*-f*, *--force*::
Force overwriting an existing role.
*-p* 'INIT_PATH', *--init-path=*'INIT_PATH'::
The path in which the skeleton role will be created.The default is the current
working directory.
*--offline*::
Don't query the galaxy API when creating roles
*--container-enabled*::
Initialize the new role with files appropriate for a Container Enabled role.
*--role-skeleton=*'ROLE_SKELETON'::
By default a new role is based on a template delivered with Ansible. Use
this option to provide an alternate template. Specify a path to a directory
that contains subdirectories and Jinja templates from which to base the new
role. Alternatively, the role_skeleton option can be configured in
*ansible.cfg*.
LIST
----
The *list* sub-command is used to show what roles are currently installed.
You can specify a role name, and if installed only that role will be shown.
USAGE
~~~~~
$ ansible-galaxy list [role_name]
OPTIONS
~~~~~~~
*-p* 'ROLES_PATH', *--roles-path=*'ROLES_PATH'::
The path to the directory containing your roles. The default is the *roles_path*
configured in your *ansible.cfg* file (/etc/ansible/roles if not configured)
SEARCH
------
The *search* sub-command returns a filtered list of roles found on the remote
server.
USAGE
~~~~~
$ ansible-galaxy search [options] [searchterm1 searchterm2]
OPTIONS
~~~~~~~
*--galaxy-tags*::
Provide a comma separated list of Galaxy Tags on which to filter.
*--platforms*::
Provide a comma separated list of Platforms on which to filter.
*--author*::
Specify the username of a Galaxy contributor on which to filter.
*-c*, *--ignore-certs*::
Ignore TLS certificate errors.
*-s*, *--server*::
Override the default server https://galaxy.ansible.com.
INFO
----
The *info* sub-command shows detailed information for a specific role.
Details returned about the role included information from the local copy
as well as information from galaxy.ansible.com.
USAGE
~~~~~
$ ansible-galaxy info [options] role_name[, version]
OPTIONS
~~~~~~~
*-p* 'ROLES_PATH', *--roles-path=*'ROLES_PATH'::
The path to the directory containing your roles. The default is the *roles_path*
configured in your *ansible.cfg* file (/etc/ansible/roles if not configured)
*-c*, *--ignore-certs*::
Ignore TLS certificate errors.
*-s*, *--server*::
Override the default server https://galaxy.ansible.com.
LOGIN
-----
The *login* sub-command is used to authenticate with galaxy.ansible.com.
Authentication is required to use the import, delete and setup commands.
It will authenticate the user, retrieve a token from Galaxy, and store it
in the user's home directory.
USAGE
~~~~~
$ ansible-galaxy login [options]
The *login* sub-command prompts for a *GitHub* username and password. It does
NOT send your password to Galaxy. It actually authenticates with GitHub and
creates a personal access token. It then sends the personal access token to
Galaxy, which in turn verifies that you are you and returns a Galaxy access
token. After authentication completes the *GitHub* personal access token is
destroyed.
If you do not wish to use your GitHub password, or if you have two-factor
authentication enabled with GitHub, use the *--github-token* option to pass a
personal access token that you create. Log into GitHub, go to Settings and
click on Personal Access Token to create a token.
OPTIONS
~~~~~~~
*-c*, *--ignore-certs*::
Ignore TLS certificate errors.
*-s*, *--server*::
Override the default server https://galaxy.ansible.com.
*--github-token*::
Authenticate using a *GitHub* personal access token rather than a password.
IMPORT
------
Import a role from *GitHub* to galaxy.ansible.com. Requires the user first
authenticate with galaxy.ansible.com using the *login* subcommand.
USAGE
~~~~~
$ ansible-galaxy import [options] github_user github_repo
OPTIONS
~~~~~~~
*-c*, *--ignore-certs*::
Ignore TLS certificate errors.
*-s*, *--server*::
Override the default server https://galaxy.ansible.com.
*--branch*::
Provide a specific branch to import. When a branch is not specified the
branch found in meta/main.yml is used. If no branch is specified in
meta/main.yml, the repo's default branch (usually master) is used.
*--role-name*::
Set the name of the role. Otherwise, the name is derived from the
name of the GitHub repository.
DELETE
------
The *delete* sub-command will delete a role from galaxy.ansible.com. Requires
the user first authenticate with galaxy.ansible.com using the *login* subcommand.
USAGE
~~~~~
$ ansible-galaxy delete [options] github_user github_repo
OPTIONS
~~~~~~~
*-c*, *--ignore-certs*::
Ignore TLS certificate errors.
*-s*, *--server*::
Override the default server https://galaxy.ansible.com.
SETUP
-----
The *setup* sub-command creates an integration point for *Travis CI*, enabling
galaxy.ansible.com to receive notifications from *Travis* on build completion.
Requires the user first authenticate with galaxy.ansible.com using the *login*
subcommand.
USAGE
~~~~~
$ ansible-galaxy setup [options] source github_user github_repo secret
* Use *travis* as the source value. In the future additional source values may
be added.
* Provide your *Travis* user token as the secret. The token is not stored by
galaxy.ansible.com. A hash is created using github_user, github_repo
and your token. The hash value is what actually gets stored.
OPTIONS
~~~~~~~
*-c*, *--ignore-certs*::
Ignore TLS certificate errors.
*-s*, *--server*::
Override the default server https://galaxy.ansible.com.
--list::
Show your configured integrations. Provides the ID of each integration
which can be used with the remove option.
--remove::
Remove a specific integration. Provide the ID of the integration to
be removed.
AUTHOR
------
Ansible was originally written by Michael DeHaan. See the AUTHORS file
for a complete list of contributors.
COPYRIGHT
---------
Copyright © 2014, Michael DeHaan
Ansible is released under the terms of the GPLv3 License.
SEE ALSO
--------
*ansible*(1), *ansible-pull*(1), *ansible-doc*(1), *ansible-playbook*(1), *ansible-vault*(1)
Extensive documentation is available in the documentation site:
<http://docs.ansible.com>. IRC and mailing list info can be found
in file CONTRIBUTING.md, available in: <https://github.com/ansible/ansible>

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

@ -1,275 +0,0 @@
ansible-playbook(1)
===================
:doctype: manpage
:man source: Ansible
:man version: %VERSION%
:man manual: System administration commands
NAME
----
ansible-playbook - run an ansible playbook
SYNOPSIS
--------
ansible-playbook <filename.yml> ... [options]
DESCRIPTION
-----------
*Ansible playbooks* are a configuration and multinode deployment
system. Ansible-playbook is the tool used to run them. See the
project home page (link below) for more information.
ARGUMENTS
---------
*filename.yml*::
The names of one or more YAML format files to run as ansible playbooks.
OPTIONS
-------
*-b*, *--become*::
Use privilege escalation (specific one depends on become_method),
this does not imply prompting for passwords.
*-K*, *--ask-become-pass*::
Ask for privilege escalation password.
*-k*, *--ask-pass*::
Prompt for the connection password, if it is needed for the transport used.
For example, using ssh and not having a key-based authentication with ssh-agent.
*--ask-su-pass*::
Prompt for su password, used with --su (deprecated, use become).
*--ask-sudo-pass*::
Prompt for the password to use with --sudo, if any (deprecated, use become).
*--ask-vault-pass*::
Prompt for vault password.
*-C*, *--check*::
Do not make any changes on the remote system, but test resources to see what might
have changed. Note this can not scan all possible resource types and is only
a simulation.
*-c* 'CONNECTION', *--connection=*'CONNECTION'::
Connection type to use. Most common options are 'paramiko' (SSH), 'ssh', 'winrm'
and 'local'. 'local' is mostly useful for crontab or kickstarts.
*-D*, *--diff*::
When changing any templated files, show the unified diffs of how they changed. When
used with --check, shows how the files would have changed if --check were not used.
*-e* 'EXTRA_VARS', *--extra-vars=*'EXTRA_VARS'::
Extra variables to inject into a playbook, in key=value key=value format or
as quoted YAML/JSON (hashes and arrays). To load variables from a file, specify
the file preceded by @ (e.g. @vars.yml).
*--flush-cache*::
Clear the fact cache.
*--force-handlers*::
Run handlers even if a task fails.
*-f* 'NUM', *--forks=*'NUM'::
Level of parallelism. 'NUM' is specified as an integer, the default is 5.
*-h*, *--help*::
Show help page and exit.
*-i* 'PATH', *--inventory=*'PATH'::
The 'PATH' to the inventory, which defaults to '/etc/ansible/hosts'.
Alternatively, you can use a comma-separated list of hosts or a single host with a trailing comma 'host,'.
*-l* 'SUBSET', *--limit=*'SUBSET'::
Further limits the selected host/group patterns.
You can prefix it with '~' to indicate that the pattern is a regex.
*--list-hosts*::
Outputs a list of matching hosts; does not execute anything else.
*--list-tags*::
List all available tags; does not execute anything else.
*--list-tasks*::
List all tasks that would be executed; does not execute anything else.
*-M* 'DIRECTORY', *--module-path=*'DIRECTORY'::
The 'DIRECTORY' search path to load modules from. The default is
'/usr/share/ansible'. This can also be set with the ANSIBLE_LIBRARY
environment variable.
*--private-key=*'PRIVATE_KEY_FILE'::
Use this file to authenticate the connection.
*--start-at-task=*'START_AT'::
Start the playbook at the task matching this name.
*--step*::
One-step-at-a-time: confirm each task before running.
*-S*, --su*::
Run operations with su (deprecated, use become).
*-R SU-USER*, *--su-user=*'SU_USER'::
Run operations with su as this user (default=root) (deprecated, use become).
*-s*, *--sudo*::
Run the command as the user given by -u and sudo to root (deprecated, use become).
*--ssh-common-args=*''-o ProxyCommand="ssh -W %h:%p ..." ...''::
Add the specified arguments to any sftp/scp/ssh command-line. Useful to
set a ProxyCommand to use a jump host, but any arguments that are
accepted by all three programs may be specified.
*--sftp-extra-args=*''-f ...''::
Add the specified arguments to any sftp command-line.
*--scp-extra-args=*''-l ...''::
Add the specified arguments to any scp command-line.
*--ssh-extra-args=*''-R ...''::
Add the specified arguments to any ssh command-line.
*-U* 'SUDO_USERNAME', *--sudo-user=*'SUDO_USERNAME'::
Sudo to 'SUDO_USERNAME' default is root. (deprecated, use become).
*--skip-tags=*'SKIP_TAGS'::
Only run plays and tasks whose tags do not match these values.
*--syntax-check*::
Look for syntax errors in the playbook, but don't run anything.
*-t*, 'TAGS', *--tags=*'TAGS'::
Only run plays and tasks tagged with these values.
*-T* 'SECONDS', *--timeout=*'SECONDS'::
Connection timeout to use when trying to talk to hosts, in 'SECONDS'.
*-u* 'USERNAME', *--user=*'USERNAME'::
Use this 'USERNAME' to login to the target host, instead of the current user.
*--vault-password-file=*'VAULT_PASSWORD_FILE'::
Vault password file.
*-v*, *--verbose*::
Verbose mode, more output from successful actions will be shown. Give
up to three times for more output.
*--version*::
Show program's version number and exit.
EXIT STATUS
-----------
*0* -- OK or no hosts matched
*1* -- Error
*2* -- One or more hosts failed
*3* -- One or more hosts were unreachable
*4* -- Parser error
*5* -- Bad or incomplete options
*99* -- User interrupted execution
*250* -- Unexpected error
ENVIRONMENT
-----------
The following environment variables may be specified:
ANSIBLE_INVENTORY -- Override the default ansible inventory file
ANSIBLE_LIBRARY -- Override the default ansible module library path
ANSIBLE_CONFIG -- Override the default ansible config file
Many more are available for most options in ansible.cfg
FILES
-----
/etc/ansible/hosts -- Default inventory file
/usr/share/ansible/ -- Default module library
/etc/ansible/ansible.cfg -- Config file, used if present
~/.ansible.cfg -- User config file, overrides the default config if present
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-pull*(1), *ansible-doc*(1), *ansible-vault*(1), *ansible-galaxy*(1)
Extensive documentation is available in the documentation site:
<http://docs.ansible.com>. IRC and mailing list info can be found
in file CONTRIBUTING.md, available in: <https://github.com/ansible/ansible>

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

@ -1,238 +0,0 @@
ansible(1)
=========
:doctype: manpage
:man source: Ansible
:man version: %VERSION%
:man manual: System administration commands
NAME
----
ansible-pull - pull playbooks from VCS server and run them using this machine as the target.
SYNOPSIS
--------
ansible-pull -U URL [options] [ <filename.yml> ]
DESCRIPTION
-----------
*Ansible* is an extra-simple tool/framework/API for doing \'remote things'.
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
a source repository. 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.
OPTIONAL ARGUMENT
-----------------
*filename.yml*::
The name of one the YAML format files to run as an ansible playbook. This can
be a relative path within the checkout. If not provided, ansible-pull
will look for a playbook based on the host's fully-qualified domain name, on the
host hostname and finally a playbook named *local.yml*.
OPTIONS
-------
*--accept-host-key*::
Adds the hostkey for the repo URL if not already added.
*-b*, *--become*::
Use privilege escalation (specific one depends on become_method),
this does not imply prompting for passwords.
*-K*, *--ask-become-pass*::
Ask for privilege escalation password.
*-k*, *--ask-pass*::
Prompt for the connection password, if it is needed for the transport used.
For example, using ssh and not having a key-based authentication with ssh-agent.
*--ask-su-pass*::
Prompt for su password, used with --su (deprecated, use become).
*--ask-sudo-pass*::
Prompt for the password to use with --sudo, if any (deprecated, use become).
*--ask-vault-pass*::
Prompt for vault password.
*-C* 'CHECKOUT', *--checkout=*'CHECKOUT'::
Branch/Tag/Commit to checkout. If not provided, uses default behavior of module used to check out playbook repository.
*-d* 'DEST', *--directory=*'DEST'::
Directory to checkout repository into. If not provided, a subdirectory of ~/.ansible/pull/ will be used.
*-e* 'EXTRA_VARS', *--extra-vars=*'EXTRA_VARS::
Extra variables to inject into a playbook, in key=value key=value format or
as quoted YAML/JSON (hashes and arrays). To load variables from a file, specify
the file preceded by @ (e.g. @vars.yml).
*-f*, *--force*::
Force running of playbook even if unable to update playbook repository. This
can be useful, for example, to enforce run-time state when a network
connection may not always be up or possible.
*--full*::
Do a full clone of the repository. By default ansible-pull will do a shallow clone based on the last revision.
*-h*, *--help*::
Show the help message and exit.
*-i* 'PATH', *--inventory=*'PATH'::
The 'PATH' to the inventory, which defaults to '/etc/ansible/hosts'.
Alternatively you can use a comma separated list of hosts or single host with traling comma 'host,'.
*--private-key=*'PRIVATE_KEY_FILE'::
Use this file to authenticate the connection.
*-m* 'NAME', *--module-name=*'NAME'::
Module used to checkout playbook repository. Defaults to git.
*-o*, *--only-if-changed*::
Only run the playbook if the repository has been updated.
*--purge*::
Purge the checkout after the playbook is run.
*-s* 'SLEEP', *--sleep=*'SLEEP'::
Sleep for random interval (between 0 and SLEEP number of seconds) before starting. This is a useful way to disperse git requests.
*--ssh-common-args=*''-o ProxyCommand="ssh -W %h:%p ..." ...''::
Add the specified arguments to any sftp/scp/ssh command-line. Useful to
set a ProxyCommand to use a jump host, but any arguments that are
accepted by all three programs may be specified.
*--sftp-extra-args=*''-f ...''::
Add the specified arguments to any sftp command-line.
*--scp-extra-args=*''-l ...''::
Add the specified arguments to any scp command-line.
*--ssh-extra-args=*''-R ...''::
Add the specified arguments to any ssh command-line.
*-t* 'TAGS', *--tags=*'TAGS'::
Only run plays and tasks tagged with these values.
*-U* 'URL', *--url=*'URL'::
URL of the playbook repository to checkout.
*--vault-password-file=*'VAULT_PASSWORD_FILE'::
Vault password file.
*--clean*::
Modified files in the working repository will be discarded.
*--track-subs*::
Submodules will track the latest changes.
*-v*, *--verbose*::
Pass -vvv to ansible-playbook.
INVENTORY
---------
Ansible stores the hosts it can potentially operate on in an inventory.
This can be an ini-like file, a script, directory or a list.
The ini syntax is one host per line. Groups headers are allowed and
are included on their own line, enclosed in square brackets that start the line.
Ranges of hosts are also supported. For more information and
additional options, see the documentation on http://docs.ansible.com/.
ENVIRONMENT
-----------
The following environment variables may be specified.
ANSIBLE_INVENTORY -- Override the default ansible inventory file
ANSIBLE_LIBRARY -- Override the default ansible module library path
ANSIBLE_CONFIG -- Override the default ansible config file
Many more are available for most options in ansible.cfg
FILES
-----
/etc/ansible/hosts -- Default inventory file
/usr/share/ansible/ -- Default module library
/etc/ansible/ansible.cfg -- Config file, used if present
~/.ansible.cfg -- User config file, overrides the default config if present
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), *ansible-doc*(1), *ansible-vault*(1), *ansible-galaxy*(1)
Extensive documentation is available in the documentation site:
<http://docs.ansible.com>. IRC and mailing list info can be found
in file CONTRIBUTING.md, available in: <https://github.com/ansible/ansible>

155
docs/man/man1/ansible-vault.1.asciidoc.in
View file

@ -1,155 +0,0 @@
ansible-vault(1)
================
:doctype: manpage
:man source: Ansible
:man version: %VERSION%
:man manual: System administration commands
NAME
----
ansible-vault - manage encrypted ansible vars files (YAML).
SYNOPSIS
--------
ansible-vault [create|decrypt|edit|encrypt|rekey] [--help] [options] file_name
DESCRIPTION
-----------
*ansible-vault* can encrypt any structured data file used by Ansible.
This can include *group_vars/* or *host_vars/* inventory variables,
variables loaded by *include_vars* or *vars_files*, or variable files
passed on the ansible-playbook command line with *-e @file.yml* or *-e @file.json*.
Role variables and defaults are also included!
Because Ansible tasks, handlers, and so on are also data, these can also be encrypted with vault.
If you’d like to not betray what variables you are even using, you can go as far to keep an individual task file entirely encrypted.
The password used with vault currently must be the same for all files you wish to use together at the same time.
COMMON OPTIONS
--------------
The following options are available to all sub-commands:
*--vault-password-file=*'FILE'::
A file containing the vault password to be used during the encryption/decryption
steps. Be sure to keep this file secured if it is used. If the file is executable,
it will be run and its standard output will be used as the password.
*--new-vault-password-file=*'FILE'::
A file containing the new vault password to be used when rekeying a
file. Be sure to keep this file secured if it is used. If the file
is executable, it will be run and its standard output will be used as
the password.
*-h*, *--help*::
Show a help message related to the given sub-command.
If '--vault-password-file' is not supplied ansible-vault will automatically prompt for passwords as required.
CREATE
------
*$ ansible-vault create [options] FILE*
The *create* sub-command is used to initialize a new encrypted file.
After providing a password, the tool will launch whatever editor you have defined
with $EDITOR, and defaults to vi. Once you are done with the editor session, the
file will be saved as encrypted data.
The default cipher is AES (which is shared-secret based).
EDIT
----
*$ ansible-vault edit [options] FILE*
The *edit* sub-command is used to modify a file which was previously encrypted using ansible-vault.
This command will decrypt the file to a temporary file and allow you to edit the file,
saving it back when done and removing the temporary file.
REKEY
-----
*$ ansible-vault rekey [options] FILE_1 [FILE_2, ..., FILE_N]*
The *rekey* command is used to change the password on a vault-encrypted files.
This command can update multiple files at once.
ENCRYPT
-------
*$ ansible-vault encrypt [options] FILE_1 [FILE_2, ..., FILE_N]*
The *encrypt* sub-command is used to encrypt pre-existing data files.
As with the *rekey* command, you can specify multiple files in one command.
The *encrypt* command accepts an *--output FILENAME* option to determine where
encrypted output is stored. With this option, input is read from the (at most one)
filename given on the command line; if no input file is given, input is read from stdin.
Either the input or the output file may be given as '-' for stdin and stdout respectively.
If neither input nor output file is given, the command acts as a filter,
reading plaintext from stdin and writing it to stdout.
Thus any of the following invocations can be used:
*$ ansible-vault encrypt*
*$ ansible-vault encrypt --output OUTFILE*
*$ ansible-vault encrypt INFILE --output OUTFILE*
*$ echo secret|ansible-vault encrypt --output OUTFILE*
Reading from stdin and writing only encrypted output is a good way to prevent
sensitive data from ever hitting disk (either interactively or from a script).
DECRYPT
-------
*$ ansible-vault decrypt [options] FILE_1 [FILE_2, ..., FILE_N]*
The *decrypt* sub-command is used to remove all encryption from data files.
The files will be stored as plain-text YAML once again, so be sure that you do not run this
command on data files with active passwords or other sensitive data.
In most cases, users will want to use the *edit* sub-command to modify the files securely.
As with *encrypt*, the *decrypt* subcommand also accepts the *--output FILENAME*
option to specify where plaintext output is stored, and stdin/stdout is handled
as described above.
AUTHOR
------
Ansible was originally written by Michael DeHaan. See the AUTHORS file
for a complete list of contributors.
COPYRIGHT
---------
Copyright © 2014, Michael DeHaan
Ansible is released under the terms of the GPLv3 License.
SEE ALSO
--------
*ansible*(1), *ansible-pull*(1), *ansible-doc*(1), *ansible-playbook*(1), *ansible-galaxy*(1)
Extensive documentation is available in the documentation site:
<http://docs.ansible.com>. IRC and mailing list info can be found
in file CONTRIBUTING.md, available in: <https://github.com/ansible/ansible>

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

@ -1,260 +0,0 @@
ansible(1)
=========
:man source: Ansible
:man version: %VERSION%
:man manual: System administration commands
NAME
----
ansible - run a task on a target host(s)
SYNOPSIS
--------
ansible <host-pattern> [-m module_name] [-a args] [options]
DESCRIPTION
-----------
*Ansible* is an extra-simple tool/framework/API for doing \'remote things'.
This is the adhoc command that allows for a \'single task playbook' run.
ARGUMENTS
---------
*host-pattern*::
A name of a group in the inventory, a shell-like glob selecting
hosts in inventory or any combination of the two separated by commas.
OPTIONS
-------
*-a* \'_ARGUMENTS_', *--args=*\'_ARGUMENTS_'::
The 'ARGUMENTS' to pass to the module.
*-b*, *--become*::
Use privilege escalation (specific one depends on become_method),
this does not imply prompting for passwords.
*-K*, *--ask-become-pass*::
Ask for privilege escalation password.
*-k*, *--ask-pass*::
Prompt for the connection password, if it is needed for the transport used.
For example, using ssh and not having a key-based authentication with ssh-agent.
*--ask-su-pass*::
Prompt for su password, used with --su (deprecated, use become).
*--ask-sudo-pass*::
Prompt for the password to use with --sudo, if any (deprecated, use become).
*--ask-vault-pass*::
Prompt for vault password.
*-B* 'NUM', *--background=*'NUM'::
Run commands in the background, killing the task after 'NUM' seconds.
*--become-method=*'BECOME_METHOD'::
Privilege escalation method to use (default=sudo),
valid choices: [ sudo | su | pbrun | pfexec | doas | dzdo | ksu ]
*--become-user=*'BECOME_USER'::
Run operations as this user (default=root).
*-C*, *--check*::
Do not make any changes on the remote system, but test resources to see what might
have changed. Note this can not scan all possible resource types and is only
a simulation.
*-c* 'CONNECTION', *--connection=*'CONNECTION'::
Connection type to use. Most common options are 'paramiko' (SSH), 'ssh', 'winrm'
and 'local'. 'local' is mostly useful for crontab or kickstarts.
*-e* 'EXTRA_VARS, *--extra-vars=*'EXTRA_VARS'::
Extra variables to inject into a playbook, in key=value key=value format or
as quoted YAML/JSON (hashes and arrays). To load variables from a file, specify
the file preceded by @ (e.g. @vars.yml).
*-f* 'NUM', *--forks=*'NUM'::
Level of parallelism. 'NUM' is specified as an integer, the default is 5.
*-h*, *--help*::
Show help message and exit.
*-i* 'PATH', *--inventory=*'PATH'::
The 'PATH' to the inventory, which defaults to '/etc/ansible/hosts'.
Alternatively you can use a comma separated list of hosts or single host with trailing comma 'host,'.
*-l* 'SUBSET', *--limit=*'SUBSET'::
Further limits the selected host/group patterns.
You can prefix it with '~' to indicate that the pattern is a regex.
*--list-hosts*::
Outputs a list of matching hosts; does not execute anything else.
*-m* 'NAME', *--module-name=*'NAME'::
Execute the module called 'NAME'.
*-M* 'DIRECTORY', *--module-path=*'DIRECTORY'::
The 'DIRECTORY' search path to load modules from. The default is
'/usr/share/ansible'. This can also be set with the ANSIBLE_LIBRARY
environment variable.
*-o*, *--one-line*::
Try to output everything on one line.
*-P* 'NUM', *--poll=*'NUM'::
Poll a background job every 'NUM' seconds. Requires *-B*.
*--private-key=*'PRIVATE_KEY_FILE'::
Use this file to authenticate the connection.
*-S*, *--su*::
Run operations with su (deprecated, use become).
*-R* 'SU_USER', *--su-user=*'SU_USER'::
Run operations with su as this user (default=root) (deprecated, use become).
*-s*, *--sudo*::
Run the command as the user given by -u and sudo to root (deprecated, use become).
*--ssh-common-args=*''-o ProxyCommand="ssh -W %h:%p ..." ...''::
Add the specified arguments to any sftp/scp/ssh command-line. Useful to
set a ProxyCommand to use a jump host, but any arguments that are
accepted by all three programs may be specified.
*--sftp-extra-args=*''-f ...''::
Add the specified arguments to any sftp command-line.
*--scp-extra-args=*''-l ...''::
Add the specified arguments to any scp command-line.
*--ssh-extra-args=*''-R ...''::
Add the specified arguments to any ssh command-line.
*-U* 'SUDO_USERNAME', *--sudo-user=*'SUDO_USERNAME'::
Sudo to 'SUDO_USERNAME' default is root. (deprecated, use become).
*-t* 'DIRECTORY', *--tree=*'DIRECTORY'::
Save contents in this output 'DIRECTORY', with the results saved in a
file named after each host.
*-T* 'SECONDS', *--timeout=*'SECONDS'::
Connection timeout to use when trying to talk to hosts, in 'SECONDS'.
*-u* 'USERNAME', *--user=*'USERNAME'::
Use this 'USERNAME' to login to the target host, instead of the current user.
*--vault-password-file=*'VAULT_PASSWORD_FILE'::
A file containing the vault password to be used during the decryption of vault encrypted files.
Be sure to keep this file secured if it is used. If the file is executable,
it will be run and its standard output will be used as the password.
*-v*, *--verbose*::
Verbose mode, more output from successful actions will be shown.
Give up to three times for more output.
*--version*::
Show program version number and exit.
INVENTORY
---------
Ansible stores the hosts it can potentially operate on in an inventory.
This can be an ini-like file, a script, directory or a list.
The ini syntax is one host per line. Groups headers are allowed and
are included on their own line, enclosed in square brackets that start the line.
Ranges of hosts are also supported. For more information and
additional options, see the documentation on http://docs.ansible.com/.
ENVIRONMENT
-----------
The following environment variables may be specified.
ANSIBLE_INVENTORY -- Override the default ansible inventory file
ANSIBLE_LIBRARY -- Override the default ansible module library path
ANSIBLE_CONFIG -- Override the default ansible config file
Many more are available for most options in ansible.cfg
FILES
-----
/etc/ansible/hosts -- Default inventory file
/usr/share/ansible/ -- Default module library
/etc/ansible/ansible.cfg -- Config file, used if present
~/.ansible.cfg -- User config file, overrides the default config if present
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-playbook*(1), *ansible-pull*(1), *ansible-doc*(1), *ansible-vault*(1), *ansible-galaxy*(1)
Extensive documentation is available in the documentation site:
<http://docs.ansible.com>. IRC and mailing list info can be found
in file CONTRIBUTING.md, available in: <https://github.com/ansible/ansible>

39
docs/templates/man.j2 vendored
View file

@ -1,5 +1,6 @@
ansible{% if cli != 'adhoc' %}-{{cli}}{% endif %}(1)
==================
{% set name = ('ansible' if cli == 'adhoc' else 'ansible-%s' % cli) -%}
{{name}}(1)
{{ '=' * ((name|length|int) + 3) }}
:doctype: manpage
:man source: Ansible
:man version: %VERSION%
@ -12,12 +13,12 @@ ansible{% if cli != 'adhoc' %}-{{cli}}{% endif %} - {{short_desc|default('')}}
SYNOPSIS
--------
{{ usage }}
{{ usage|replace('%prog', name) }}
DESCRIPTION
-----------
{{ long_desc }}
*{{name}}* {{ long_desc|default('', True)|wordwrap }}
{% if arguments %}
@ -25,13 +26,24 @@ ARGUMENTS
---------
{% for arg in arguments %}
{{ arg['name'] }}
{{ arg }}
{{ arg['desc'] }}
{{ (arguments[arg]|default(' '))|wordwrap }}
{% endfor %}
{% endif %}
{% if actions %}
ACTIONS
-------
{% for action in actions %}
{{ action }}
{{ (actions[action]|default(' '))|wordwrap}}
{% endfor %}
{% endif %}
OPTIONS
-------
@ -41,7 +53,7 @@ OPTIONS
{{ option['desc'] }}
{% endfor %}
{% if inv_opts %}
{% if inventory %}
INVENTORY
---------
@ -55,11 +67,11 @@ ENVIRONMENT
The following environment variables may be specified.
{% if inv_opts %}
{% if inventory %}
ANSIBLE_INVENTORY -- Override the default ansible inventory file
{% endif %}
{% if run_opts %}
{% if library %}
ANSIBLE_LIBRARY -- Override the default ansible module library path
{% endif %}
@ -71,7 +83,7 @@ Many more are available for most options in ansible.cfg
FILES
-----
{% if inv_opts %}
{% if inventory %}
/etc/ansible/hosts -- Default inventory file
{% endif %}
@ -90,7 +102,7 @@ See the AUTHORS file for a complete list of contributors.
COPYRIGHT
---------
Copyright © 2017 Red Hat, Inc.
Copyright © 2017 Red Hat, Inc | Ansible.
Ansible is released under the terms of the GPLv3 License.
@ -100,5 +112,6 @@ SEE ALSO
{% for other in cli_list|sort %}{% if other != cli %}*ansible{% if other != 'adhoc' %}-{{other}}{% endif %}*(1){% if not loop.last %}, {% endif %}{% endif %}{% endfor %}
Extensive documentation is available in the documentation site:
<http://docs.ansible.com>. IRC and mailing list info can be found
in file CONTRIBUTING.md, available in: <https://github.com/ansible/ansible>
<http://docs.ansible.com>.
IRC and mailing list info can be found in file CONTRIBUTING.md,
available in: <https://github.com/ansible/ansible>

2
docs/templates/playbooks_keywords.rst.j2 vendored
View file

@ -5,6 +5,8 @@ Here we list the common playbook objects and their directives.
Note that not all directives affect the object itself and might just be there to be inherited by other contained objects.
Aliases for the directives are not reflected here, nor are mutable ones, for example `action` in task can be substituted by the name of any module plugin.
Be aware that this reflects the 'current development branch' and that the keywords do not have 'version_added' information.
.. contents::
:local:
:depth: 1

53
lib/ansible/cli/__init__.py
View file

@ -93,7 +93,7 @@ class InvalidOptsParser(SortedOptParser):
class CLI(with_metaclass(ABCMeta, object)):
''' code behind bin/ansible* programs '''
VALID_ACTIONS = ['No Actions']
VALID_ACTIONS = []
_ITALIC = re.compile(r"I\(([^)]+)\)")
_BOLD = re.compile(r"B\(([^)]+)\)")
@ -283,7 +283,8 @@ class CLI(with_metaclass(ABCMeta, object)):
@staticmethod
def base_parser(usage="", output_opts=False, runas_opts=False, meta_opts=False, runtask_opts=False, vault_opts=False, module_opts=False,
async_opts=False, connect_opts=False, subset_opts=False, check_opts=False, inventory_opts=False, epilog=None, fork_opts=False, runas_prompt_opts=False, desc=None):
async_opts=False, connect_opts=False, subset_opts=False, check_opts=False, inventory_opts=False, epilog=None, fork_opts=False,
runas_prompt_opts=False, desc=None):
''' create an options parser for most ansible scripts '''
# base opts
@ -665,51 +666,3 @@ class CLI(with_metaclass(ABCMeta, object)):
data = data.split(os.pathsep)[0]
return data
def _opt_doc_list(self, action=None):
''' generate options docs '''
if action:
self.args.append(action)
self.set_action()
results = []
for opt in self.parser.option_list:
res = {
'desc': opt.help,
'options': opt._short_opts + opt._long_opts
}
if opt.action == 'store':
res['arg'] = opt.dest.upper()
results.append(res)
return results
def opts_docs(self, args=None):
''' generate doc structure from options '''
# cli name
name = os.path.basename(sys.argv[0])
if '-' in name:
name = name.split('-')[1]
else:
name = 'adhoc'
# cli info
docs = {
'cli': name,
'usage': self.parser.usage,
'short_desc': self.parser.description
}
if self.VALID_ACTIONS:
myopts = []
for action in self.VALID_ACTIONS:
newopts = self._opt_doc_list(action)
for nopt in newopts:
if nopt not in myopts:
myopts.append(nopt)
docs['options'] = myopts
else:
docs['options'] = self._opt_doc_list()
return docs

4
lib/ansible/cli/adhoc.py
View file

@ -46,7 +46,9 @@ except ImportError:
########################################################
class AdHocCLI(CLI):
''' Ad-hoc Ansible allows you to define and run a single task 'playbook' against a set of hosts '''
''' is an extra-simple tool/framework/API for doing 'remote things'.
this command allows you to define and run a single task 'playbook' against a set of hosts
'''
def parse(self):
''' create an options parser for bin/ansible '''

5
lib/ansible/cli/console.py
View file

@ -58,8 +58,13 @@ except ImportError:
class ConsoleCLI(CLI, cmd.Cmd):
''' a REPL that allows for running ad-hoc tasks against a chosen inventory (based on dominis' ansible-shell).'''
modules = []
ARGUMENTS = {
'host-pattern': 'A name of a group in the inventory, a shell-like glob '
'selecting hosts in inventory or any combination of the two separated by commas.',
}
def __init__(self, args):

5
lib/ansible/cli/doc.py
View file

@ -40,7 +40,10 @@ except ImportError:
class DocCLI(CLI):
""" Doc command line class """
''' displays information on modules installed in Ansible libraries.
It displays a terse listing of plugins and their short descriptions,
provides a printout of their DOCUMENTATION strings,
and it can create a short "snippet" which can be pasted into a playbook. '''
def __init__(self, args):

65
lib/ansible/cli/galaxy.py
View file

@ -50,6 +50,7 @@ except ImportError:
class GalaxyCLI(CLI):
'''command to manage Ansible roles in shared repostories, the default of which is Ansible Galaxy *https://galaxy.ansible.com*.'''
SKIP_INFO_KEYS = ("name", "description", "readme_html", "related", "summary_fields", "average_aw_composite", "average_aw_score", "url" )
VALID_ACTIONS = ("delete", "import", "info", "init", "install", "list", "login", "remove", "search", "setup")
@ -59,20 +60,10 @@ class GalaxyCLI(CLI):
self.galaxy = None
super(GalaxyCLI, self).__init__(args)
def parse(self):
''' create an options parser for bin/ansible '''
def set_action(self):
self.parser = CLI.base_parser(
usage = "usage: %%prog [%s] [--help] [options] ..." % "|".join(self.VALID_ACTIONS),
epilog = "\nSee '%s <command> --help' for more information on a specific command.\n\n" % os.path.basename(sys.argv[0])
)
super(GalaxyCLI, self).set_action()
self.set_action()
# common
self.parser.add_option('-s', '--server', dest='api_server', default=C.GALAXY_SERVER, help='The API server destination')
self.parser.add_option('-c', '--ignore-certs', action='store_true', dest='ignore_certs', default=C.GALAXY_IGNORE_CERTS,
help='Ignore SSL certificate validation errors.')
# specific to actions
if self.action == "delete":
@ -135,6 +126,20 @@ class GalaxyCLI(CLI):
if self.action in ("init","install"):
self.parser.add_option('-f', '--force', dest='force', action='store_true', default=False, help='Force overwriting an existing role')
def parse(self):
''' create an options parser for bin/ansible '''
self.parser = CLI.base_parser(
usage = "usage: %%prog [%s] [--help] [options] ..." % "|".join(self.VALID_ACTIONS),
epilog = "\nSee '%s <command> --help' for more information on a specific command.\n\n" % os.path.basename(sys.argv[0])
)
# common
self.parser.add_option('-s', '--server', dest='api_server', default=C.GALAXY_SERVER, help='The API server destination')
self.parser.add_option('-c', '--ignore-certs', action='store_true', dest='ignore_certs', default=C.GALAXY_IGNORE_CERTS,
help='Ignore SSL certificate validation errors.')
self.set_action()
super(GalaxyCLI, self).parse()
display.verbosity = self.options.verbosity
@ -182,8 +187,7 @@ class GalaxyCLI(CLI):
def execute_init(self):
"""
Executes the init action, which creates the skeleton framework
of a role that complies with the galaxy metadata format.
creates the skeleton framework of a role that complies with the galaxy metadata format.
"""
init_path = self.get_opt('init_path', './')
@ -255,9 +259,7 @@ class GalaxyCLI(CLI):
def execute_info(self):
"""
Executes the info action. This action prints out detailed
information about an installed role as well as info available
from the galaxy API.
prints out detailed information about an installed role as well as info available from the galaxy API.
"""
if len(self.args) == 0:
@ -304,10 +306,8 @@ class GalaxyCLI(CLI):
def execute_install(self):
"""
Executes the installation action. The args list contains the
roles to be installed, unless -f was specified. The list of roles
can be a name (which will be downloaded via the galaxy API and github),
or it can be a local .tar.gz file.
uses the args list of roles to be installed, unless -f was specified. The list of roles
can be a name (which will be downloaded via the galaxy API and github), or it can be a local .tar.gz file.
"""
role_file = self.get_opt("role_file", None)
@ -432,8 +432,7 @@ class GalaxyCLI(CLI):
def execute_remove(self):
"""
Executes the remove action. The args list contains the list
of roles to be removed. This list can contain more than one role.
removes the list of roles passed as arguments from the local system.
"""
if len(self.args) == 0:
@ -453,10 +452,7 @@ class GalaxyCLI(CLI):
def execute_list(self):
"""
Executes the list action. The args list can contain zero
or one role. If one is specified, only that role will be
shown, otherwise all roles in the specified directory will
be shown.
lists the roles installed on the local system or matches a single role passed as an argument.
"""
if len(self.args) > 1:
@ -500,6 +496,7 @@ class GalaxyCLI(CLI):
return 0
def execute_search(self):
''' searches for roles on the Ansible Galaxy server'''
page_size = 1000
search = None
@ -544,7 +541,7 @@ class GalaxyCLI(CLI):
def execute_login(self):
"""
Verify user's identify via Github and retrieve an auth token from Galaxy.
verify user's identify via Github and retrieve an auth token from Ansible Galaxy.
"""
# Authenticate with github and retrieve a token
if self.options.token is None:
@ -567,9 +564,7 @@ class GalaxyCLI(CLI):
return 0
def execute_import(self):
"""
Import a role into Galaxy
"""
""" used to import a role into Ansible Galaxy """
colors = {
'INFO': 'normal',
@ -625,9 +620,7 @@ class GalaxyCLI(CLI):
return 0
def execute_setup(self):
"""
Setup an integration from Github or Travis
"""
""" Setup an integration from Github or Travis for Ansible Galaxy roles"""
if self.options.setup_list:
# List existing integration secrets
@ -664,9 +657,7 @@ class GalaxyCLI(CLI):
return 0
def execute_delete(self):
"""
Delete a role from galaxy.ansible.com
"""
""" Delete a role from Ansible Galaxy. """
if len(self.args) < 2:
raise AnsibleError("Missing one or more arguments. Expected: github_user github_repo")

4
lib/ansible/cli/playbook.py
View file

@ -44,7 +44,9 @@ except ImportError:
#---------------------------------------------------------------------------------------------------
class PlaybookCLI(CLI):
''' code behind ansible playbook cli'''
''' the tool to run *Ansible playbooks*, which are a configuration and multinode deployment system.
See the project home page (https://docs.ansible.com) for more information. '''
def parse(self):

36
lib/ansible/cli/pull.py
View file

@ -44,7 +44,16 @@ except ImportError:
########################################################
class PullCLI(CLI):
''' code behind ansible ad-hoc cli'''
''' is used to up a remote copy of ansible on each managed node,
each set to run via cron and update playbook source via a source repository.
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.
'''
DEFAULT_REPO_TYPE = 'git'
DEFAULT_PLAYBOOK = 'local.yml'
@ -53,12 +62,18 @@ class PullCLI(CLI):
2: 'File is not readable'
}
SUPPORTED_REPO_MODULES = ['git']
ARGUMENTS = {
'playbook.yml': 'The name of one the YAML format files to run as an Ansible playbook.'
'This can be a relative path within the checkout. By default, Ansible will'
"look for a playbook based on the host's fully-qualified domain name,"
'on the host hostname and finally a playbook named *local.yml*.',
}
def parse(self):
''' create an options parser for bin/ansible '''
self.parser = CLI.base_parser(
usage='%prog -U <repository> [options]',
usage='%prog -U <repository> [options] [<playbook.yml>]',
connect_opts=True,
vault_opts=True,
runtask_opts=True,
@ -70,22 +85,18 @@ class PullCLI(CLI):
)
# options unique to pull
self.parser.add_option('--purge', default=False, action='store_true',
help='purge checkout after playbook run')
self.parser.add_option('--purge', default=False, action='store_true', help='purge checkout after playbook run')
self.parser.add_option('-o', '--only-if-changed', dest='ifchanged', default=False, action='store_true',
help='only run the playbook if the repository has been updated')
self.parser.add_option('-s', '--sleep', dest='sleep', default=None,
help='sleep for random interval (between 0 and n number of seconds) before starting. This is a useful way to disperse git requests')
self.parser.add_option('-f', '--force', dest='force', default=False, action='store_true',
help='run the playbook even if the repository could not be updated')
self.parser.add_option('-d', '--directory', dest='dest', default=None,
help='directory to checkout repository to')
self.parser.add_option('-U', '--url', dest='url', default=None,
help='URL of the playbook repository')
self.parser.add_option('--full', dest='fullclone', action='store_true',
help='Do a full clone, instead of a shallow one.')
self.parser.add_option('-d', '--directory', dest='dest', default=None, help='directory to checkout repository to')
self.parser.add_option('-U', '--url', dest='url', default=None, help='URL of the playbook repository')
self.parser.add_option('--full', dest='fullclone', action='store_true', help='Do a full clone, instead of a shallow one.')
self.parser.add_option('-C', '--checkout', dest='checkout',
help='branch/tag/commit to checkout. ' 'Defaults to behavior of repository module.')
help='branch/tag/commit to checkout. Defaults to behavior of repository module.')
self.parser.add_option('--accept-host-key', default=False, dest='accept_host_key', action='store_true',
help='adds the hostkey for the repo url if not already added')
self.parser.add_option('-m', '--module-name', dest='module_name', default=self.DEFAULT_REPO_TYPE,
@ -96,8 +107,7 @@ class PullCLI(CLI):
self.parser.add_option('--clean', dest='clean', default=False, action='store_true',
help='modified files in the working repository will be discarded')
self.parser.add_option('--track-subs', dest='tracksubs', default=False, action='store_true',
help='submodules will track the latest changes'
' This is equivalent to specifying the --remote flag to git submodule update')
help='submodules will track the latest changes. This is equivalent to specifying the --remote flag to git submodule update')
# for pull we don't wan't a default
self.parser.set_defaults(inventory=None)

41
lib/ansible/cli/vault.py
View file

@ -36,7 +36,17 @@ except ImportError:
class VaultCLI(CLI):
""" Vault command line class """
''' can encrypt any structured data file used by Ansible.
This can include *group_vars/* or *host_vars/* inventory variables,
variables loaded by *include_vars* or *vars_files*, or variable files
passed on the ansible-playbook command line with *-e @file.yml* or *-e @file.json*.
Role variables and defaults are also included!
Because Ansible tasks, handlers, and so on are also data, these can also be encrypted with vault.
If you'd like to not betray what variables you are even using, you can go as far to keep an individual task file entirely encrypted.
The password used with vault currently must be the same for all files you wish to use together at the same time.
'''
VALID_ACTIONS = ("create", "decrypt", "edit", "encrypt", "encrypt_string", "rekey", "view")
@ -51,16 +61,9 @@ class VaultCLI(CLI):
self.encrypt_string_read_stdin = False
super(VaultCLI, self).__init__(args)
def parse(self):
def set_action(self):
self.parser = CLI.base_parser(
vault_opts=True,
usage = "usage: %%prog [%s] [options] [vaultfile.yml]" % "|".join(self.VALID_ACTIONS),
desc = "encryption/decryption utility for Ansbile data files",
epilog = "\nSee '%s <command> --help' for more information on a specific command.\n\n" % os.path.basename(sys.argv[0])
)
self.set_action()
super(VaultCLI, self).set_action()
# options specific to self.actions
if self.action == "create":
@ -88,6 +91,17 @@ class VaultCLI(CLI):
elif self.action == "rekey":
self.parser.set_usage("usage: %prog rekey [options] file_name")
def parse(self):
self.parser = CLI.base_parser(
vault_opts=True,
usage = "usage: %%prog [%s] [options] [vaultfile.yml]" % "|".join(self.VALID_ACTIONS),
desc = "encryption/decryption utility for Ansbile data files",
epilog = "\nSee '%s <command> --help' for more information on a specific command.\n\n" % os.path.basename(sys.argv[0])
)
self.set_action()
super(VaultCLI, self).parse()
display.verbosity = self.options.verbosity
@ -162,6 +176,7 @@ class VaultCLI(CLI):
os.umask(old_umask)
def execute_encrypt(self):
''' encrypt the supplied file using the provided vault secret '''
if len(self.args) == 0 and sys.stdin.isatty():
display.display("Reading plaintext input from stdin", stderr=True)
@ -191,6 +206,7 @@ class VaultCLI(CLI):
return yaml_ciphertext
def execute_encrypt_string(self):
''' encrypt the supplied string using the provided vault secret '''
b_plaintext = None
# Holds tuples (the_text, the_source_of_the_string, the variable name if its provided).
@ -314,6 +330,7 @@ class VaultCLI(CLI):
return output
def execute_decrypt(self):
''' decrypt the supplied file using the provided vault secret '''
if len(self.args) == 0 and sys.stdin.isatty():
display.display("Reading ciphertext input from stdin", stderr=True)
@ -325,6 +342,7 @@ class VaultCLI(CLI):
display.display("Decryption successful", stderr=True)
def execute_create(self):
''' create and open a file in an editor that will be encryped with the provided vault secret when closed'''
if len(self.args) > 1:
raise AnsibleOptionsError("ansible-vault create can take only one filename argument")
@ -332,10 +350,12 @@ class VaultCLI(CLI):
self.editor.create_file(self.args[0])
def execute_edit(self):
''' open and decrypt an existing vaulted file in an editor, that will be encryped again when closed'''
for f in self.args:
self.editor.edit_file(f)
def execute_view(self):
''' open, decrypt and view an existing vaulted file using a pager using the supplied vault secret '''
for f in self.args:
# Note: vault should return byte strings because it could encrypt
@ -346,6 +366,7 @@ class VaultCLI(CLI):
self.pager(to_text(self.editor.plaintext(f)))
def execute_rekey(self):
''' re-encrypt a vaulted file with a new secret, the previous secret is required '''
for f in self.args:
if not (os.path.isfile(f)):
raise AnsibleError(f + " does not exist")

4
test/sanity/pep8/legacy-files.txt
View file

@ -38,14 +38,14 @@ contrib/inventory/windows_azure.py
contrib/inventory/zabbix.py
contrib/inventory/zone.py
docs/api/conf.py
docs/bin/dump_keywords.py
docs/bin/plugin_formatter.py
docs/docsite/conf.py
docs/docsite/rst/conf.py
examples/scripts/uptime.py
hacking/cherrypick.py
hacking/dump_playbook_attributes.py
hacking/get_library.py
hacking/metadata-tool.py
hacking/module_formatter.py
hacking/tests/gen_distribution_version_testcase.py
lib/ansible/cli/__init__.py
lib/ansible/cli/adhoc.py