From b0d503338661d43845146324eddbea670e3efb73 Mon Sep 17 00:00:00 2001 From: Michael DeHaan Date: Fri, 4 Oct 2013 18:14:54 -0400 Subject: [PATCH] Add lots of anchor tags. --- docsite/latest/rst/intro_adhoc.rst | 16 ++ docsite/latest/rst/intro_configuration.rst | 146 +++++++++++++---- .../latest/rst/intro_dynamic_inventory.rst | 8 + docsite/latest/rst/intro_getting_started.rst | 8 + docsite/latest/rst/intro_installation.rst | 147 +++--------------- docsite/latest/rst/intro_inventory.rst | 10 ++ 6 files changed, 181 insertions(+), 154 deletions(-) diff --git a/docsite/latest/rst/intro_adhoc.rst b/docsite/latest/rst/intro_adhoc.rst index 48ed991035..06949f537f 100644 --- a/docsite/latest/rst/intro_adhoc.rst +++ b/docsite/latest/rst/intro_adhoc.rst @@ -35,6 +35,8 @@ and then we'll get going. .. contents:: :depth: 2 +.. _parallelism_and_shell_commands: + Parallelism and Shell Commands `````````````````````````````` @@ -108,6 +110,7 @@ simple scripts. They make the remote system look like you state, and run the com get it there. This is commonly referred to as 'idempotence', and is a core design goal of ansible. However, we also recognize that running arbitrary commands is equally important, so Ansible easily supports both. +.. _file_transfer: File Transfer ````````````` @@ -135,6 +138,7 @@ As well as delete directories (recursively) and delete files:: $ ansible webservers -m file -a "dest=/path/to/c state=absent" +.. _managing_packages: Managing Packages ````````````````` @@ -163,6 +167,8 @@ does not have a module available for it, you can install for other packages using the command module or (better!) contribute a module for other package managers. Stop by the mailing list for info/details. +.. _users_and_groups: + Users and Groups ```````````````` @@ -177,6 +183,8 @@ exist:: See the :doc:`modules` section for details on all of the available options, including how to manipulate groups and group membership. +.. _from_source_control: + Deploying From Source Control ````````````````````````````` @@ -189,6 +197,8 @@ tell ansible to run specific tasks when the code is updated, such as deploying Perl/Python/PHP/Ruby directly from git and then restarting apache. +.. _managing_services: + Managing Services ````````````````` @@ -204,6 +214,8 @@ Ensure a service is stopped:: $ ansible webservers -m service -a "name=httpd state=stopped" +.. _time_limited_background_operations: + Time Limited Background Operations `````````````````````````````````` @@ -233,6 +245,8 @@ the remote nodes will be terminated. Typically you'll be only be backgrounding long-running shell commands or software upgrades only. Backgrounding the copy module does not do a background file transfer. :doc:`playbooks` also support polling, and have a simplified syntax for this. +.. _checking_facts: + Gathering Facts ``````````````` @@ -245,6 +259,8 @@ Its also possible to filter this output to just export certain facts, see the "s Read more about facts at :doc:`playbooks_variables` once you're ready to read up on :doc:`playbooks`. +.. _limiting_hosts: + Limiting Selected Hosts ``````````````````````` diff --git a/docsite/latest/rst/intro_configuration.rst b/docsite/latest/rst/intro_configuration.rst index f0acf6368d..2e41123886 100644 --- a/docsite/latest/rst/intro_configuration.rst +++ b/docsite/latest/rst/intro_configuration.rst @@ -19,6 +19,8 @@ The last file in the list is found and the others will be ignored. .. contents:: :depth: 2 +.. _getting_the_latest_configuration: + Getting the latest configuration ```````````````````````````````` @@ -31,6 +33,8 @@ default settings in Ansible. You may wish to consult the `ansible.cfg in source control _` for all of the possible latest values. +.. _environmental_configuration: + Environmental configuration ``````````````````````````` @@ -39,14 +43,20 @@ override any setting loaded from the configuration file. These variables are fo in the source tree if you want to use these. They are mostly considered to be a legacy system as compared to the config file, but are equally valid. +.. _config_values_by_section: + Explanation of values by section ```````````````````````````````` +.. _general_defaults: + General defaults ---------------- In the [defaults] section of ansible.cfg, the following settings are tunable: +.. _action_plugins: + action_plugins ============== @@ -59,6 +69,8 @@ different locations:: Most users will not need to use this feature. See :doc:`developing_plugins` for more details. +.. _ansible_managed: + ansible_managed =============== @@ -73,6 +85,8 @@ The default configuration shows who modified a file and when:: This is useful to tell users that a file has been placed by Ansible and manual changes are likely to be overwritten. +.. _ask_pass: + ask_pass ======== @@ -82,6 +96,8 @@ This controls whether an Ansible playbook should prompt for a password by defaul If using SSH keys for authentication, it's probably not needed to change this setting. +.. _ask_sudo_pass: + ask_sudo_pass ============= @@ -92,6 +108,8 @@ sudoing. The default behavior is also no:: Users on platforms where sudo passwords are enabled should consider changing this setting. +.. _callback_plugins: + callback_plugins ================ @@ -102,6 +120,8 @@ different locations:: Most users will not need to use this feature. See :doc:`developing_plugins` for more details +.. _connection_plugins: + connection_plugins ================== @@ -112,6 +132,8 @@ different locations:: Most users will not need to use this feature. See :doc:`developing_plugins` for more details +.. _display_skipped_hosts: + display_skipped_hosts ===================== @@ -121,6 +143,8 @@ If set to `False`, ansible will not display any status for a task that is skippe Note that Ansible will always show the task header for any task, regardless of whether or not the task is skipped. +.. _error_on_undefined_vars: + error_on_undefined_vars ======================= @@ -132,6 +156,8 @@ typoed:: If set to False, any '{{ template_expression }}' that contains undefined variables will be rendered in a template or ansible action line exactly as written. +.. _executable: + executable ========== @@ -140,6 +166,20 @@ rare instances to /bin/bash in rare instances wehn sudo is constrained, but in m #executable = /bin/bash +.. _filter_plugins: + +filter_plugins +============== + +This is a developer-centric feature that allows low-level extensions around Ansible to be loaded from +different locations:: + + action_plugins = /usr/share/ansible_plugins/action_plugins + +Most users will not need to use this feature. See :doc:`developing_plugins` for more details + +.. _forks: + forks ===== @@ -151,24 +191,6 @@ is very very conservative:: forks=5 -pattern -======= - -This is the default group of hosts to talk to in a playbook if no "hosts:" stanza is supplied. The default is to talk -to all hosts. You may wish to change this to protect yourself from surprises:: - - hosts=* - -Note that /usr/bin/ansible always requires a host pattern and does not use this setting, only /usr/bin/ansible-playbook. - -poll_interval -============= - -For asynchronous tasks in Ansible (covered in :doc:`playbooks_async`), this is how often to check back on the status of those -tasks when an explicit poll interval is not supplied. The default is a reasonably moderate 15 seconds which is a tradeoff -between checking in frequently and providing a quick turnaround when something may have completed:: - - poll_interval=15 hash_behavior ============= @@ -184,6 +206,8 @@ official examples repos do not use this setting:: The valid values are either 'replace' (the default) or 'merge'. +.. _hostfile: + hostfile ======== @@ -192,6 +216,8 @@ to talk to:: hostfile = /etc/ansible/hosts +.. _host_key_checking: + host_key_checking ================= @@ -200,15 +226,7 @@ implications and wish to disable it, you may do so here by setting the value to host_key_checking=True -filter_plugins -============== - -This is a developer-centric feature that allows low-level extensions around Ansible to be loaded from -different locations:: - - action_plugins = /usr/share/ansible_plugins/action_plugins - -Most users will not need to use this feature. See :doc:`developing_plugins` for more details +.. _jinja2_extensions: jinja2_extensions ================= @@ -219,6 +237,8 @@ This is a developer-specific feature that allows enabling additional Jinja2 exte If you do not know what these do, you probably don't need to change this setting :) +.. _legacy_playbook_variables: + legacy_playbook_variables ========================= @@ -231,6 +251,8 @@ still enabled as of Ansible 1.4) can be disabled like so :: legacy_playbook_variables = no +.. _library: + library ======= @@ -241,6 +263,8 @@ This is the default location Ansible looks to find modules:: Ansible knows how to look in multiple locations if you feed it a colon seperated path, and it also will look for modules in the "./library" directory alongside a playbook. +.. _log_path: + log_path ======== @@ -251,6 +275,8 @@ the user running Ansible has permissions on the logfile. This behavior is not on by default. +.. _lookup_plugins: + lookup_plugins ============== @@ -261,6 +287,8 @@ different locations:: Most users will not need to use this feature. See :doc:`developing_plugins` for more details +.. _module_name: + module_name =========== @@ -270,6 +298,8 @@ it to 'shell':: module_name = command +.. _nocolor: + nocolor ======= @@ -278,6 +308,8 @@ If you dislike this behavior you can turn it off by setting 'nocolor' to 0:: nocolor=0 +.. _nocows: + nocows ====== @@ -287,6 +319,31 @@ by setting 'nocows' to 1:: nocows=0 +.. _pattern: + +pattern +======= + +This is the default group of hosts to talk to in a playbook if no "hosts:" stanza is supplied. The default is to talk +to all hosts. You may wish to change this to protect yourself from surprises:: + + hosts=* + +Note that /usr/bin/ansible always requires a host pattern and does not use this setting, only /usr/bin/ansible-playbook. + +.. _poll_interval: + +poll_interval +============= + +For asynchronous tasks in Ansible (covered in :doc:`playbooks_async`), this is how often to check back on the status of those +tasks when an explicit poll interval is not supplied. The default is a reasonably moderate 15 seconds which is a tradeoff +between checking in frequently and providing a quick turnaround when something may have completed:: + + poll_interval=15 + +.. _private_key_file: + private_key_file ================ @@ -295,6 +352,8 @@ value here to avoid re-specifying --ansible-private-keyfile with every invocatio private_key_file=/path/to/file.pem +.. _remote_port: + remote_port =========== @@ -303,6 +362,8 @@ The default is the standard 22:: remote_port = 22 +.. _remote_tmp: + remote_tmp ========== @@ -315,6 +376,8 @@ setting:: The default is to use a subdirectory of the user's home directory. Ansible will then choose a random directory name inside this location. +.. _remote_user: + remote_user =========== @@ -323,6 +386,7 @@ always default to the current user:: remote_user = root +.. _sudo_exe: sudo_exe ======== @@ -332,6 +396,8 @@ the sudo implementation is matching CLI flags with the standard sudo:: sudo_exe=sudo +.. _sudo_flags: + sudo_flags ========== @@ -341,6 +407,8 @@ will not need to change this setting:: sudo_flags=-H +.. _sudo_user: + sudo_user ========= @@ -349,6 +417,7 @@ playbook. The default is the most logical: 'root':: sudo_user=root +.. _timeout: timeout ======= @@ -357,6 +426,8 @@ This is the default SSH timeout to use on connection attempts:: timeout = 10 +.. _transport: + transport ========= @@ -367,6 +438,8 @@ technology, and then will otherwise use 'paramiko'. Other transport options inc Users should usually leave this setting as 'smart' and let their playbooks choose an alternate setting when needed with the 'connection:' play parameter. +.. _vars_plugins: + vars_plugins ============ @@ -377,6 +450,7 @@ different locations:: Most users will not need to use this feature. See :doc:`developing_plugins` for more details +.. _paramiko_settings: Paramiko Specific Settings -------------------------- @@ -384,6 +458,8 @@ Paramiko Specific Settings Paramiko is the default SSH connection implementation on Enterprise Linux 6 or earlier, and is not used by default on other platforms. Settings live under the [paramiko] header. +.. _record_host_keys: + record_host_keys ================ @@ -393,12 +469,16 @@ instead. Setting it to False will improve performance and is recommended when h record_host_keys=True +.. _openssh_settings: + OpenSSH Specific Settings ------------------------- Under the [ssh] header, the following settings are tunable for SSH connections. OpenSSH is the default connection type for Ansible on OSes that are new enough to support ControlPersist. (This means basically all operating systems except Enterprise Linux 6 or earlier). +.. _ssh_args: + ssh_args ======== @@ -409,6 +489,8 @@ If set, this will pass a specific set of options to Ansible rather than Ansible' In particular, users may wish to raise the ControlPersist time to encourage performance. A value of 30 minutes may be appropriate. +.. _control_path: + control_path ============ @@ -427,6 +509,8 @@ Ansible 1.4 and later will instruct users to run with "-vvvv" in situations wher and if so it is easy to tell there is too long of a Control Path filename. This may be frequently encountered on EC2. +.. _scp_if_ssh: + scp_if_ssh ========== @@ -438,11 +522,15 @@ cause scp to be used to transfer remote files instead:: There's really no reason to change this unless problems are encountered, and then there's also no real drawback to managing the switch. Most environments support SFTP by default and this doesn't usually need to be changed. +.. _accelerate_settings: + Accelerate Mode Settings ------------------------ Under the [accelerate] header, the following settings are tunable for :doc:`playbooks_acceleration` +.. _accelerate_port: + accelerate_port =============== @@ -452,6 +540,8 @@ This is the port to use for accelerate mode:: accelerate_port = 5099 +.. _accelerate_timeout: + accelerate_timeout ================== @@ -461,6 +551,8 @@ This setting controls the timeout for receiving data from a client. If no data i accelerate_timeout = 30 +.. _accelerate_connect_timeout: + accelerate_connect_timeout ========================== diff --git a/docsite/latest/rst/intro_dynamic_inventory.rst b/docsite/latest/rst/intro_dynamic_inventory.rst index b017174ccc..89a2e813c7 100644 --- a/docsite/latest/rst/intro_dynamic_inventory.rst +++ b/docsite/latest/rst/intro_dynamic_inventory.rst @@ -14,6 +14,8 @@ Ansible easily supports all of these options via an external inventory system. For information about writing your own, see :doc:`developing_inventory`. +.. _cobbler_example: + Example: The Cobbler External Inventory Script `````````````````````````````````````````````` @@ -71,6 +73,8 @@ And technically, though there is no major good reason to do it, this also works So in other words, you can use those variables in arguments/actions as well. +.. _aws_example: + Example: AWS EC2 External Inventory Script `````````````````````````````````````````` @@ -182,6 +186,8 @@ To see the complete list of variables available for an instance, run the script 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. +.. _other_inventory_scripts: + Other inventory scripts ``````````````````````` @@ -202,6 +208,8 @@ it should be very obvious how to use them. The process for the AWS inventory sc If you develop an interesting inventory script that might be general purpose, please submit a pull request -- we'd likely be glad to include it in the project. +.. _using_multiple_sources: + Using Multiple Inventory Sources ```````````````````````````````` diff --git a/docsite/latest/rst/intro_getting_started.rst b/docsite/latest/rst/intro_getting_started.rst index a894cf193b..ec8d7ab97e 100644 --- a/docsite/latest/rst/intro_getting_started.rst +++ b/docsite/latest/rst/intro_getting_started.rst @@ -4,6 +4,8 @@ Getting Started .. contents:: :depth: 2 +.. _gs_about: + About ````` @@ -16,6 +18,8 @@ Playbooks are covered in a seperate section. This is basically about how to get going initially. Once you have this down, read :doc:`intro_adhoc` for some more detail, and then you'll be ready to dive into playbooks. +.. _remote_connection_information: + Remote Connection Information ````````````````````````````` @@ -39,6 +43,8 @@ While it may be common sense, it is worth sharing: Any management system benefit 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. +.. _your_first_commands: + Your first commands ``````````````````` @@ -98,6 +104,8 @@ what you can do with different modules, as well as the Ansible also has powerful configuration management and deployment features. There's more to explore, but you already have a fully working infrastructure! +.. _a_note_about_host_key_checking: + A note about Host Key Checking `````````````````````````````` diff --git a/docsite/latest/rst/intro_installation.rst b/docsite/latest/rst/intro_installation.rst index ef493be057..6d47635206 100644 --- a/docsite/latest/rst/intro_installation.rst +++ b/docsite/latest/rst/intro_installation.rst @@ -4,6 +4,8 @@ Installation .. contents:: :depth: 2 +.. _getting_ansible: + Getting Ansible ``````````````` @@ -11,6 +13,8 @@ You may also wish to follow the `Github project