From f3e416f065b5f9503e775d86f29b562391ff480c Mon Sep 17 00:00:00 2001 From: Matt Jaynes Date: Tue, 21 Jan 2014 22:05:21 -0700 Subject: [PATCH] Minor documentation fixes. Fixed double-dash literals. Fixed broken :doc: links. Minor case fixes. Minor wording fixes. --- docsite/rst/developing_inventory.rst | 8 ++++---- docsite/rst/glossary.rst | 10 +++++----- docsite/rst/index.rst | 2 +- docsite/rst/intro_dynamic_inventory.rst | 2 +- docsite/rst/intro_getting_started.rst | 10 +++++----- docsite/rst/intro_installation.rst | 16 +++++++--------- docsite/rst/intro_patterns.rst | 2 +- docsite/rst/playbooks_best_practices.rst | 4 ++-- docsite/rst/playbooks_checkmode.rst | 10 +++++----- docsite/rst/playbooks_intro.rst | 4 ++-- docsite/rst/playbooks_variables.rst | 6 +++--- 11 files changed, 36 insertions(+), 38 deletions(-) diff --git a/docsite/rst/developing_inventory.rst b/docsite/rst/developing_inventory.rst index 4630b71114a..11cb8b342db 100644 --- a/docsite/rst/developing_inventory.rst +++ b/docsite/rst/developing_inventory.rst @@ -16,7 +16,7 @@ You can do this in any language. Script Conventions `````````````````` -When the external node script is called with the single argument '--list', the script must return a JSON hash/dictionary of all the groups to be managed. Each group's value should be either a hash/dictionary containing a list of each host/IP, potential child groups, and potential group variables, or simply a list of host/IP addresses, like so:: +When the external node script is called with the single argument ``--list``, the script must return a JSON hash/dictionary of all the groups to be managed. Each group's value should be either a hash/dictionary containing a list of each host/IP, potential child groups, and potential group variables, or simply a list of host/IP addresses, like so:: { "databases" : { @@ -41,7 +41,7 @@ When the external node script is called with the single argument '--list', the s Before version 1.0, each group could only have a list of hostnames/IP addresses, like the webservers, marietta, and 5points groups above. -When called with the arguments '--host ' (where is a host from above), the script must return either an empty JSON +When called with the arguments ``--host `` (where is a host from above), the script must return either an empty JSON hash/dictionary, or a hash/dictionary of variables to make available to templates and playbooks. Returning variables is optional, if the script does not wish to do this, returning an empty hash/dictionary is the way to go:: @@ -59,11 +59,11 @@ Tuning the External Inventory Script .. versionadded:: 1.3 The stock inventory script system detailed above works for all versions of Ansible, but calling -'--host' for every host can be rather expensive, especially if it involves expensive API calls to +``--host`` for every host can be rather expensive, especially if it involves expensive API calls to a remote subsystem. In Ansible 1.3 or later, if the inventory script returns a top level element called "_meta", it is possible to return all of the host variables in one inventory script call. When this meta element contains -a value for "hostvars", the inventory script will not be invoked with "--host" for each host. This +a value for "hostvars", the inventory script will not be invoked with ``--host`` for each host. This results in a significant performance increase for large numbers of hosts, and also makes client side caching easier to implement for the inventory script. diff --git a/docsite/rst/glossary.rst b/docsite/rst/glossary.rst index 352e808481b..f4d2679c60d 100644 --- a/docsite/rst/glossary.rst +++ b/docsite/rst/glossary.rst @@ -37,7 +37,7 @@ in the GitHub project perform custom logging, send email, or even play sound eff Check Mode ++++++++++ -Refers to running Ansible with the --check option, which does not make any changes on the remote systems, but only outputs the changes that +Refers to running Ansible with the ``--check`` option, which does not make any changes on the remote systems, but only outputs the changes that might occur if the command ran without this flag. This is analogous to so-called "dry run" modes in other systems, though the user should be warned that this does not take into account unexpected command failures or cascade effects (which is true of similar modes in other systems). Use this to get an idea of what might happen, but it is not a substitute for a good staging environment. @@ -62,8 +62,8 @@ discussed in the playbook documentation. Diff Mode +++++++++ -A --diff flag can be passed to Ansible to show how template files change when they are overwritten, or how they might change when used -with --check mode. These diffs come out in unified diff format. +A ``--diff`` flag can be passed to Ansible to show how template files change when they are overwritten, or how they might change when used +with ``--check`` mode. These diffs come out in unified diff format. Facts +++++ @@ -93,7 +93,7 @@ self destruct after a set period of time. This means the bus does not allow man Forks +++++ -Ansible talks to remote nodes in parallel and the level of parallelism can be set either by passing --forks, or editing the default in a configuration +Ansible talks to remote nodes in parallel and the level of parallelism can be set either by passing ``--forks``, or editing the default in a configuration file. The default is a very conservative 5 forks, though if you have a lot of RAM, you can easily set this to a value like 50 for increased parallelism. @@ -228,7 +228,7 @@ A collection of modules made available to /usr/bin/ansible or an Ansible playboo Limit Groups ++++++++++++ -By passing "--limit somegroup" to ansible or ansible-playbook, the commands can be limited to a subset of hosts. For instance, +By passing ``--limit somegroup`` to ansible or ansible-playbook, the commands can be limited to a subset of hosts. For instance, this can be used to run a playbook that normally targets an entire set of servers to one particular server. Local Connection diff --git a/docsite/rst/index.rst b/docsite/rst/index.rst index 75eb96a416c..f086e82cf33 100644 --- a/docsite/rst/index.rst +++ b/docsite/rst/index.rst @@ -9,7 +9,7 @@ Welcome to the Ansible documentation! Ansible is an IT automation tool. It can configure systems, deploy software, and orchestrate more advanced IT tasks such as continuous deployments or zero downtime rolling updates. -Ansible's goals are foremost those of simplicity and maximum ease of use. It also has a strong focus on security and reliability, featuring a minimum of moving parts, usage of Open SSH for transport (with an accelerated socket mode and pull modes as alternatives), and a language that is designed around auditability by humans -- even those not familiar with the program. +Ansible's goals are foremost those of simplicity and maximum ease of use. It also has a strong focus on security and reliability, featuring a minimum of moving parts, usage of OpenSSH for transport (with an accelerated socket mode and pull modes as alternatives), and a language that is designed around auditability by humans -- even those not familiar with the program. We believe simplicity is relevant to all sizes of environments and design for busy users of all types -- whether this means developers, sysadmins, release engineers, IT managers, and everywhere in between. Ansible is appropriate for managing small setups with a handful of instances as well as enterprise environments with many thousands. diff --git a/docsite/rst/intro_dynamic_inventory.rst b/docsite/rst/intro_dynamic_inventory.rst index 11a2dda9a59..859c2499d72 100644 --- a/docsite/rst/intro_dynamic_inventory.rst +++ b/docsite/rst/intro_dynamic_inventory.rst @@ -186,7 +186,7 @@ To see the complete list of variables available for an instance, run the script ./ec2.py --host ec2-12-12-12-12.compute-1.amazonaws.com Note that the AWS inventory script will cache results to avoid repeated API calls, and this cache setting is configurable in ec2.ini. To -explicitly clear the cache, you can run the ec2.py script with the '--refresh-cache' parameter. +explicitly clear the cache, you can run the ec2.py script with the ``--refresh-cache`` parameter. .. _other_inventory_scripts: diff --git a/docsite/rst/intro_getting_started.rst b/docsite/rst/intro_getting_started.rst index ae1172d3075..6edd035b074 100644 --- a/docsite/rst/intro_getting_started.rst +++ b/docsite/rst/intro_getting_started.rst @@ -26,16 +26,16 @@ Before we get started, it's important to understand how Ansible is communicating machines over SSH. By default, Ansible 1.3 and later will try to use native -OpenSSH for remote communication when possible. This enables both ControlPersist (a performance feature), Kerberos, and options in ~/.ssh/config such as Jump Host setup. When using Enterprise Linux 6 operating systems as the control machine (Red Hat Enterprise Linux and derivatives such as CentOS), however, the version of OpenSSH may be too old to support Control Persist. On these operating systems, Ansible will fallback into using a high-quality python implementation of +OpenSSH for remote communication when possible. This enables both ControlPersist (a performance feature), Kerberos, and options in ~/.ssh/config such as Jump Host setup. When using Enterprise Linux 6 operating systems as the control machine (Red Hat Enterprise Linux and derivatives such as CentOS), however, the version of OpenSSH may be too old to support ControlPersist. On these operating systems, Ansible will fallback into using a high-quality Python implementation of OpenSSH called 'paramiko'. If you wish to use features like Kerberized SSH and more, consider using Fedora, OS X, or Ubuntu as your control machine until a newer version of OpenSSH is available for your platform -- or engage 'accelerated mode' in Ansible. See :doc:`playbooks_acceleration`. In Ansible 1.2 and before, the default was strictly paramiko and native SSH had to be explicitly selected with -c ssh or set in the configuration file. Occasionally you'll encounter a device that doesn't do SFTP. This is rare, but if talking with some remote devices that don't support SFTP, you can switch to SCP mode in :doc:`intro_configuration`. -When speaking with remote machines, Ansible will by default assume you are using SSH keys -- which we encourage -- but passwords are fine too. To enable password auth, supply the option --ask-pass where needed. If using sudo features and when sudo requires a password, also supply --ask-sudo-pass as appropriate. +When speaking with remote machines, Ansible will by default assume you are using SSH keys -- which we encourage -- but passwords are fine too. To enable password auth, supply the option ``--ask-pass`` where needed. If using sudo features and when sudo requires a password, also supply ``--ask-sudo-pass`` as appropriate. -While it may be common sense, it is worth sharing: Any management system benefits from being run near your machines you are being managed. If running in a cloud, consider running Ansible from a machine inside that cloud. It will work better than on the open +While it may be common sense, it is worth sharing: Any management system benefits from being run near the machines being managed. If running in a cloud, consider running Ansible from a machine inside that cloud. It will work better than on the open intranet in most cases. As an advanced topic, Ansible doesn't just have to connect remotely over SSH. The transports are pluggable, and there are options for managing things locally, as well as managing chroot, lxc, and jail containers. A mode called 'ansible-pull' can also invert the system and have systems 'phone home' via scheduled git checkouts to pull configuration directives from a central repository. @@ -64,7 +64,7 @@ do: $ ssh-agent bash $ ssh-add ~/.ssh/id_rsa -(Depending on your setup, you may wish to use Ansible's --private-key option to specify a pem file instead) +(Depending on your setup, you may wish to use Ansible's ``--private-key`` option to specify a pem file instead) Now ping all your nodes: @@ -127,7 +127,7 @@ Also note that host key checking in paramiko mode is reasonably slow, therefore .. _a_note_about_logging: Ansible will log some information about module arguments on the remote system in the remote syslog. To enable basic -logging on the control machine see `intro_config` document and set the 'log_path' configuration file setting. Enterprise users may also be interested in `AnsibleWorks AWX `_. AWX provides a very robust database logging feature where it is possible to drill down and see history based on hosts, projects, and particular inventories over time -- explorable both graphically and through a REST API. +logging on the control machine see :doc:`intro_configuration` document and set the 'log_path' configuration file setting. Enterprise users may also be interested in `AnsibleWorks AWX `_. AWX provides a very robust database logging feature where it is possible to drill down and see history based on hosts, projects, and particular inventories over time -- explorable both graphically and through a REST API. .. seealso:: diff --git a/docsite/rst/intro_installation.rst b/docsite/rst/intro_installation.rst index 39ffecc4837..6cf9376ed37 100644 --- a/docsite/rst/intro_installation.rst +++ b/docsite/rst/intro_installation.rst @@ -19,7 +19,7 @@ Basics / What Will Be Installed Ansible by default manages machines over the SSH protocol. -Once ansible is installed, it will not add a database, and there will be no daemons to start or keep running. You only need to install it on one machine (which could easily be a laptop) and it can manage an entire fleet of remote machines from that central point. When Ansible manages remote machines, it does not leave software installed or running on them, so there's no real question about how to upgrade Ansible when moving to a new version. +Once Ansible is installed, it will not add a database, and there will be no daemons to start or keep running. You only need to install it on one machine (which could easily be a laptop) and it can manage an entire fleet of remote machines from that central point. When Ansible manages remote machines, it does not leave software installed or running on them, so there's no real question about how to upgrade Ansible when moving to a new version. .. _what_version: @@ -46,7 +46,7 @@ information about running from source. It's not necessary to install the progra Control Machine Requirements ```````````````````````````` -Currently Ansible can be from any machine with Python 2.6 installed (Windows isn't supported for the control machine). +Currently Ansible can be run from any machine with Python 2.6 installed (Windows isn't supported for the control machine). This includes Red Hat, Debian, CentOS, OS X, any of the BSDs, and so on. @@ -76,10 +76,10 @@ On the managed nodes, you only need Python 2.4 or later, but if you are are runn .. note:: - Python 3 is a slightly different language than Python 2 and most python programs (including + Python 3 is a slightly different language than Python 2 and most Python programs (including Ansible) are not switching over yet. However, some Linux distributions (Gentoo, Arch) may not have a Python 2.X interpreter installed by default. On those systems, you should install one, and set - the 'ansible_python_interpreter' variable in inventory (see :doc:`intro_inventory`) to point at your 2.X python. Distributions + the 'ansible_python_interpreter' variable in inventory (see :doc:`intro_inventory`) to point at your 2.X Python. Distributions like Red Hat Enterprise Linux, CentOS, Fedora, and Ubuntu all have a 2.X interpreter installed by default and this does not apply to those distributions. This is also true of nearly all Unix systems. If you need to bootstrap these remote systems by installing Python 2.X, @@ -148,7 +148,7 @@ RPMs are available from yum for `EPEL Fedora distributions. Ansible itself can manage earlier operating -systems that contain python 2.4 or higher (so also EL5). +systems that contain Python 2.4 or higher (so also EL5). Fedora users can install Ansible directly, though if you are using RHEL or CentOS and have not already done so, `configure EPEL `_ @@ -210,11 +210,9 @@ Readers that use virtualenv can also install Ansible under virtualenv, though we Tarballs of Tagged Releases +++++++++++++++++++++++++++ -Packaging Ansible or wanting to build a local package yourself, but don't want to do a git checkout? Tarballs of releases are available on the ansibleworks.com page. +Packaging Ansible or wanting to build a local package yourself, but don't want to do a git checkout? Tarballs of releases are available on the `Ansible/downloads `_ page. -* `Ansible/downloads `_ - -These releases are also tagged in the git repository with the release version. +These releases are also tagged in the `git repository `_ with the release version. .. seealso:: diff --git a/docsite/rst/intro_patterns.rst b/docsite/rst/intro_patterns.rst index 7d8ebe0f528..1dd1935f060 100644 --- a/docsite/rst/intro_patterns.rst +++ b/docsite/rst/intro_patterns.rst @@ -72,7 +72,7 @@ Most people don't specify patterns as regular expressions, but you can. Just st ~(web|db).*\.example\.com -While we're jumping a bit ahead, additionally, you can add an exclusion criteria just by supplying the "--limit" flag to /usr/bin/ansible or /usr/bin/ansible-playbook:: +While we're jumping a bit ahead, additionally, you can add an exclusion criteria just by supplying the ``--limit`` flag to /usr/bin/ansible or /usr/bin/ansible-playbook:: ansible-playbook site.yml --limit datacenter2 diff --git a/docsite/rst/playbooks_best_practices.rst b/docsite/rst/playbooks_best_practices.rst index efa4a4cc321..8a2a0e8c152 100644 --- a/docsite/rst/playbooks_best_practices.rst +++ b/docsite/rst/playbooks_best_practices.rst @@ -359,8 +359,8 @@ Keep It Simple When you can do something simply, do something simply. Do not reach to use every feature of Ansible together, all at once. Use what works -for you. For example, you will probably not need 'vars', -'vars_files', 'vars_prompt' and '--extra-vars' all at once, +for you. For example, you will probably not need ``vars``, +``vars_files``, ``vars_prompt`` and ``--extra-vars`` all at once, while also using an external inventory file. .. _version_control: diff --git a/docsite/rst/playbooks_checkmode.rst b/docsite/rst/playbooks_checkmode.rst index cc34ff5bdfc..77bae8df4d6 100644 --- a/docsite/rst/playbooks_checkmode.rst +++ b/docsite/rst/playbooks_checkmode.rst @@ -5,7 +5,7 @@ Check Mode ("Dry Run") .. contents:: Topics -When ansible-playbook is executed with --check it will not make any changes on remote systems. Instead, any module +When ansible-playbook is executed with ``--check`` it will not make any changes on remote systems. Instead, any module instrumented to support 'check mode' (which contains most of the primary core modules, but it is not required that all modules do this) will report what changes they would have made rather than making them. Other modules that do not support check mode will also take no action, but just will not report what changes they might have made. @@ -42,13 +42,13 @@ true. .. _diff_mode: -Showing Differences with --diff -``````````````````````````````` +Showing Differences with ``--diff`` +``````````````````````````````````` .. versionadded:: 1.1 -The --diff option to ansible-playbook works great with --check (detailed above) but can also be used by itself. When this flag is supplied, if any templated files on the remote system are changed, and the ansible-playbook CLI will report back -the textual changes made to the file (or, if used with --check, the changes that would have been made). Since the diff +The ``--diff`` option to ansible-playbook works great with ``--check`` (detailed above) but can also be used by itself. When this flag is supplied, if any templated files on the remote system are changed, and the ansible-playbook CLI will report back +the textual changes made to the file (or, if used with ``--check``, the changes that would have been made). Since the diff feature produces a large amount of output, it is best used when checking a single host at a time, like so:: ansible-playbook foo.yml --check --diff --limit foo.example.com diff --git a/docsite/rst/playbooks_intro.rst b/docsite/rst/playbooks_intro.rst index becead2ea07..db82e2c483a 100644 --- a/docsite/rst/playbooks_intro.rst +++ b/docsite/rst/playbooks_intro.rst @@ -348,7 +348,7 @@ run ansible-playbook against that content. Assuming you load balance your checkout location, ansible-pull scales essentially infinitely. -Run 'ansible-pull --help' for details. +Run ``ansible-pull --help`` for details. There's also a `clever playbook `_ available to using ansible in push mode to configure ansible-pull via a crontab! @@ -362,7 +362,7 @@ and how they performed. General failures and fatal "unreachable" communication kept separate in the counts. If you ever want to see detailed output from successful modules as well as unsuccessful ones, -use the '--verbose' flag. This is available in Ansible 0.5 and later. +use the ``--verbose`` flag. This is available in Ansible 0.5 and later. Ansible playbook output is vastly upgraded if the cowsay package is installed. Try it! diff --git a/docsite/rst/playbooks_variables.rst b/docsite/rst/playbooks_variables.rst index 61e231ed119..64cae20767f 100644 --- a/docsite/rst/playbooks_variables.rst +++ b/docsite/rst/playbooks_variables.rst @@ -500,9 +500,9 @@ Similarly, the hostname as the system reports it is:: {{ ansible_hostname }} -Facts are frequently used in conditionals (see `playbook_conditionals`) and also in templates. +Facts are frequently used in conditionals (see :doc:`playbook_conditionals`) and also in templates. -Facts can be also used to create dynamic groups of hosts that match particular criteria, see the :doc:`modules` documentation on 'group_by' for details, as well as in generalized conditional statements as discussed in the `playbook_conditionals` chapter. +Facts can be also used to create dynamic groups of hosts that match particular criteria, see the :doc:`modules` documentation on 'group_by' for details, as well as in generalized conditional statements as discussed in the :doc:`playbook_conditionals` chapter. .. _disabling_facts: @@ -848,7 +848,7 @@ roles aren't you? Hint hint. Ok, so if you are writing a redistributable role with reasonable defaults, put those in the 'roles/x/defaults/main.yml' file. This means the role will bring along a default value but ANYTHING in Ansible will override it. It's just a default. That's why it says "defaults" :) -See `intro_roles` for more info about this:: +See :doc:`playbooks_roles` for more info about this:: --- # file: roles/x/defaults/main.yml