ja/LC_MESSAGES/user_guide.po

6 msgid ""
20 msgid "Ansible concepts"
24 msgid "These concepts are common to all uses of Ansible. You need to understand them to use Ansible…
28 msgid "Control node"
32 msgid "Any machine with Ansible installed. You can run Ansible commands and playbooks by invoking t…
36 msgid "Managed nodes"
40 msgid "The network devices (and/or servers) you manage with Ansible. Managed nodes are also sometim…
44 msgid "Inventory"
48 msgid "A list of managed nodes. An inventory file is also sometimes called a \"hostfile\". Your inv…
52 msgid "Collections"
56 msgid "Collections are a distribution format for Ansible content that can include playbooks, roles,…
60 msgid "Modules"
64 msgid "The units of code Ansible executes. Each module has a particular use, from administering use…
68 msgid "Tasks"
72 msgid "The units of action in Ansible. You can execute a single task once with an ad hoc command."
76 msgid "Playbooks"
80 msgid "Ordered lists of tasks, saved so you can run those tasks in that order repeatedly. Playbooks…
84 msgid "Understanding privilege escalation: become"
88 msgid "Ansible uses existing privilege escalation systems to execute tasks with root privileges or …
92 msgid "Using become"
96 msgid "You can control the use of ``become`` with play or task directives, connection variables, or…
100 msgid "A full list of all become plugins that are included in Ansible can be found in the :ref:`bec…
104 msgid "Become directives"
108 msgid "You can set the directives that control ``become`` at the play or task level. You can overri…
112 msgid "become"
116 msgid "set to ``yes`` to activate privilege escalation."
120 msgid "become_user"
124 msgid "set to user with desired privileges — the user you `become`, NOT the user you login as. Does…
128 msgid "become_method"
132 msgid "(at play or task level) overrides the default method set in ansible.cfg, set to use any of t…
136 msgid "become_flags"
140 msgid "(at play or task level) permit the use of specific flags for the tasks or role. One common u…
144 msgid "For example, to manage a system service (which requires ``root`` privileges) when connected …
148 msgid "To run a command as the ``apache`` user:"
152 msgid "To do something as the ``nobody`` user when the shell is nologin:"
156 msgid "To specify a password for sudo, run ``ansible-playbook`` with ``--ask-become-pass`` (``-K`` …
160 msgid "Become connection variables"
164 msgid "You can define different ``become`` options for each managed node or group. You can define t…
170 msgid "ansible_become"
174 msgid "overrides the ``become`` directive, decides if privilege escalation is used or not."
179 msgid "ansible_become_method"
183 msgid "which privilege escalation method should be used"
188 msgid "ansible_become_user"
192 msgid "set the user you become through privilege escalation; does not imply ``ansible_become: yes``"
197 msgid "ansible_become_password"
201 msgid "set the privilege escalation password. See :ref:`playbooks_vault` for details on how to avoi…
205 msgid "ansible_common_remote_group"
209 msgid "determines if Ansible should try to ``chgrp`` its temporary files to a group if ``setfacl`` …
213 msgid "For example, if you want to run all tasks as ``root`` on a server named ``webserver``, but y…
217 msgid "The variables defined above are generic for all become plugins but plugin specific ones can …
221 msgid "Become command-line options"
225 msgid "ask for privilege escalation password; does not imply become will be used. Note that this pa…
229 msgid "run operations with become (no password implied)"
233 msgid "privilege escalation method to use (default=sudo), valid choices: [ sudo | su | pbrun | pfex…
237 msgid "run operations as this user (default=root), does not imply --become/-b"
241 msgid "Risks and limitations of become"
245 msgid "Although privilege escalation is mostly intuitive, there are a few limitations on how it wor…
249 msgid "Risks of becoming an unprivileged user"
253 msgid "Ansible modules are executed on the remote machine by first substituting the parameters into…
257 msgid "Everything is fine if the module file is executed without using ``become``, when the ``becom…
261 msgid "However, when both the connection user and the ``become_user`` are unprivileged, the module …
265 msgid "First, if :command:`setfacl` is installed and available in the remote ``PATH``, and the temp…
269 msgid "Next, if POSIX ACLs are **not** available or :command:`setfacl` could not be run, Ansible wi…
273 msgid "New in Ansible 2.11, at this point, Ansible will try :command:`chmod +a` which is a macOS-sp…
277 msgid "New in Ansible 2.10, if all of the above fails, Ansible will then check the value of the con…
281 msgid "At this point, if ``ansible_common_remote_group`` was defined and a :command:`chgrp` was att…
285 msgid "If ``ansible_common_remote_group`` is **not** set and the chown above it failed, or if ``ans…
289 msgid "Once the module is done executing, Ansible deletes the temporary file."
293 msgid "Several ways exist to avoid the above logic flow entirely:"
297 msgid "Use `pipelining`.  When pipelining is enabled, Ansible does not save the module to a tempora…
301 msgid "Avoid becoming an unprivileged user.  Temporary files are protected by UNIX file permissions…
305 msgid "Although the Solaris ZFS filesystem has filesystem ACLs, the ACLs are not POSIX.1e filesyste…
309 msgid "Ansible makes it hard to unknowingly use ``become`` insecurely. Starting in Ansible 2.1, Ans…
313 msgid "Ansible 2.10 introduces the above-mentioned ``ansible_common_remote_group`` fallback. As men…
317 msgid "As mentioned above, if ``ansible_common_remote_group`` and ``allow_world_readable_tmpfiles``…
321 msgid "Not supported by all connection plugins"
325 msgid "Privilege escalation methods must also be supported by the connection plugin used. Most conn…
329 msgid "Only one method may be enabled per host"
333 msgid "Methods cannot be chained. You cannot use ``sudo /bin/su -`` to become a user, you need to h…
337 msgid "Privilege escalation must be general"
341 msgid "You cannot limit privilege escalation permissions to certain commands. Ansible does not alwa…
345 msgid "May not access environment variables populated by pamd_systemd"
349 msgid "For most Linux distributions using ``systemd`` as their init, the default methods used by ``…
353 msgid "This might cause trouble when trying to invoke systemd commands that depend on ``XDG_RUNTIME…
357 msgid "To force ``become`` to open a new systemd session that goes through ``pam_systemd``, you can…
361 msgid "For more information, see `this systemd issue <https://github.com/systemd/systemd/issues/825…
365 msgid "Become and network automation"
369 msgid "As of version 2.6, Ansible supports ``become`` for privilege escalation (entering ``enable``…
373 msgid "You must set the connection type to either ``connection: ansible.netcommon.network_cli`` or …
377 msgid "You can use escalated privileges on only the specific tasks that need them, on an entire pla…
381 msgid "If you see this error message, the task that generated it requires ``enable`` mode to succee…
385 msgid "To set ``enable`` mode for a specific task, add ``become`` at the task level:"
389 msgid "To set enable mode for all tasks in a single play, add ``become`` at the play level:"
393 msgid "Setting enable mode for all tasks"
397 msgid "Often you wish for all tasks in all plays to run using privilege mode, that is best achieved…
401 msgid "**group_vars/eos.yml**"
405 msgid "Passwords for enable mode"
409 msgid "If you need a password to enter ``enable`` mode, you can specify it in one of two ways:"
413 msgid "providing the :option:`--ask-become-pass <ansible-playbook --ask-become-pass>` command line …
417 msgid "setting the ``ansible_become_password`` connection variable"
421 msgid "As a reminder passwords should never be stored in plain text. For information on encrypting …
425 msgid "authorize and auth_pass"
429 msgid "Ansible still supports ``enable`` mode with ``connection: local`` for legacy network playboo…
433 msgid "We recommend updating your playbooks to use ``become`` for network-device ``enable`` mode co…
437 msgid "Become and Windows"
441 msgid "Since Ansible 2.3, ``become`` can be used on Windows hosts through the ``runas`` method. Bec…
445 msgid "While ``become`` can be used to assume the identity of another user, there are other uses fo…
449 msgid "Administrative rights"
453 msgid "Many tasks in Windows require administrative privileges to complete. When using the ``runas`…
457 msgid "A user must have the ``SeDebugPrivilege`` to run a become process with elevated privileges. …
461 msgid "To determine the type of token that Ansible was able to get, run the following task:"
465 msgid "The output will look something similar to the below:"
469 msgid "Under the ``label`` key, the ``account_name`` entry determines whether the user has Administ…
473 msgid "``Medium``: Ansible failed to get an elevated token and ran under a limited token. Only a su…
477 msgid "``High``: An elevated token was used and all the privileges assigned to the user are availab…
481 msgid "``System``: The ``NT AUTHORITY\\System`` account is used and has the highest level of privil…
485 msgid "The output will also show the list of privileges that have been granted to the user. When th…
489 msgid "If running on a version of Ansible that is older than 2.5 or the normal ``runas`` escalation…
493 msgid "Set the ``become_user`` to ``System`` which has full control over the operating system."
497 msgid "Grant ``SeTcbPrivilege`` to the user Ansible connects with on WinRM. ``SeTcbPrivilege`` is a…
501 msgid "Turn UAC off on the host and reboot before trying to become the user. UAC is a security prot…
505 msgid "Granting the ``SeTcbPrivilege`` or turning UAC off can cause Windows security vulnerabilitie…
509 msgid "Local service accounts"
513 msgid "Prior to Ansible version 2.5, ``become`` only worked on Windows with a local or domain user …
517 msgid "System"
521 msgid "NetworkService"
525 msgid "LocalService"
529 msgid "Because local service accounts do not have passwords, the ``ansible_become_password`` parame…
533 msgid "Become without setting a password"
537 msgid "As of Ansible 2.8, ``become`` can be used to become a Windows local or domain account withou…
541 msgid "The connection user has the ``SeDebugPrivilege`` privilege assigned"
545 msgid "The connection user is part of the ``BUILTIN\\Administrators`` group"
549 msgid "The ``become_user`` has either the ``SeBatchLogonRight`` or ``SeNetworkLogonRight`` user rig…
553 msgid "Using become without a password is achieved in one of two different methods:"
557 msgid "Duplicating an existing logon session's token if the account is already logged on"
561 msgid "Using S4U to generate a logon token that is valid on the remote host only"
565 msgid "In the first scenario, the become process is spawned from another logon of that user account…
569 msgid "In the case where another logon of the become account does not exist, S4U is used to create …
573 msgid "To make a distinction between using become with no password and becoming an account that has…
577 msgid "Because there are no guarantees an existing token will exist for a user when Ansible runs, t…
581 msgid "Accounts without a password"
585 msgid "As a general security best practice, you should avoid allowing accounts without passwords."
589 msgid "Ansible can be used to become a Windows account that does not have a password (like the ``Gu…
593 msgid "Before become can work on an account like this, the local policy `Accounts: Limit local acco…
597 msgid "This is only for accounts that do not have a password. You still need to set the account's p…
601 msgid "Become flags for Windows"
605 msgid "Ansible 2.5 added the ``become_flags`` parameter to the ``runas`` become method. This parame…
609 msgid "These flags should only be set when becoming a normal user account, not a local service acco…
613 msgid "The key ``logon_type`` sets the type of logon operation to perform. The value can be set to …
617 msgid "``interactive``: The default logon type. The process will be run under a context that is the…
621 msgid "``batch``: Runs the process under a batch context that is similar to a scheduled task with a…
625 msgid "``new_credentials``: Runs under the same credentials as the calling user, but outbound conne…
629 msgid "``network``: Runs the process under a network context without any cached credentials. This r…
633 msgid "``network_cleartext``: Like the ``network`` logon type, but instead caches the credentials s…
637 msgid "For more information, see `dwLogonType <https://docs.microsoft.com/en-gb/windows/desktop/api…
641 msgid "The ``logon_flags`` key specifies how Windows will log the user on when creating the new pro…
645 msgid "``with_profile``: The default logon flag set. The process will load the user's profile in th…
649 msgid "``netcredentials_only``: The process will use the same token as the caller but will use the …
653 msgid "By default ``logon_flags=with_profile`` is set, if the profile should not be loaded set ``lo…
657 msgid "For more information, see `dwLogonFlags <https://docs.microsoft.com/en-gb/windows/desktop/ap…
661 msgid "Here are some examples of how to use ``become_flags`` with Windows tasks:"
665 msgid "Limitations of become on Windows"
669 msgid "Running a task with ``async`` and ``become`` on Windows Server 2008, 2008 R2 and Windows 7 o…
673 msgid "By default, the become user logs on with an interactive session, so it must have the right t…
677 msgid "Prior to Ansible version 2.3, become only worked when ``ansible_winrm_transport`` was either…
681 msgid "The Secondary Logon service ``seclogon`` must be running to use ``ansible_become_method: run…
685 msgid "`Mailing List <https://groups.google.com/forum/#!forum/ansible-project>`_"
703 msgid "Questions? Help? Ideas?  Stop by the list on Google Groups"
740 msgid "`irc.libera.chat <https://libera.chat/>`_"
777 msgid "#ansible IRC chat channel"
781 msgid "Using collections"
785 msgid "Collections are a distribution format for Ansible content that can include playbooks, roles,…
789 msgid "You can install and use collections through `Ansible Galaxy <https://galaxy.ansible.com>`_."
793 msgid "For details on how to *develop* collections see :ref:`developing_collections`."
797 msgid "For the current development status of Collections and FAQ see `Ansible Collections Community…
801 msgid "Installing collections"
805 msgid "If you install a collection manually as described in this paragraph, the collection will not…
809 msgid "Installing collections with ``ansible-galaxy``"
813 msgid "By default, ``ansible-galaxy collection install`` uses https://galaxy.ansible.com as the Gal…
817 msgid "See :ref:`Configuring the ansible-galaxy client <galaxy_server_config>` if you are using any…
821 msgid "To install a collection hosted in Galaxy:"
825 msgid "To upgrade a collection to the latest available version from the Galaxy server you can use t…
829 msgid "You can also directly use the tarball from your build:"
833 msgid "You can build and install a collection from a local source directory. The ``ansible-galaxy``…
837 msgid "You can also install multiple collections in a namespace directory."
841 msgid "The install command automatically appends the path ``ansible_collections`` to the one specif…
845 msgid "When using the ``-p`` option to specify the install path, use one of the values configured i…
849 msgid "You can also keep a collection adjacent to the current playbook, under a ``collections/ansib…
853 msgid "See :ref:`collection_structure` for details on the collection directory structure."
857 msgid "Installing an older version of a collection"
861 msgid "You can only have one version of a collection installed at a time. By default ``ansible-gala…
865 msgid "You can specify multiple range identifiers separated by ``,``. Use single quotes so the shel…
869 msgid "Ansible will always install the most recent version that meets the range identifiers you spe…
873 msgid "``*``: The most recent version. This is the default."
877 msgid "``!=``: Not equal to the version specified."
881 msgid "``==``: Exactly the version specified."
885 msgid "``>=``: Greater than or equal to the version specified."
889 msgid "``>``: Greater than the version specified."
893 msgid "``<=``: Less than or equal to the version specified."
897 msgid "``<``: Less than the version specified."
901 msgid "By default ``ansible-galaxy`` ignores pre-release versions. To install a pre-release version…
905 msgid "Installing a collection from a git repository"
909 msgid "You can install a collection in a git repository by providing the URI to the repository inst…
913 msgid "Embedding credentials into a git URI is not secure. Make sure to use safe auth options for s…
917 msgid "In a ``requirements.yml`` file, you can also use the ``type`` and ``version`` keys in additi…
921 msgid "Git repositories can be used for collection dependencies as well. This can be helpful for lo…
925 msgid "Default repository search locations"
929 msgid "There are two paths searched in a repository for collections by default."
933 msgid "The first is the ``galaxy.yml`` or ``MANIFEST.json`` file in the top level of the repository…
937 msgid "The second is a ``galaxy.yml`` or ``MANIFEST.json`` file in each directory in the repository…
941 msgid "Specifying the location to search for collections"
945 msgid "If you have a different repository structure or only want to install a subset of collections…
949 msgid "Install multiple collections with a requirements file"
953 msgid "You can also setup a ``requirements.yml`` file to install multiple collections in one comman…
957 msgid "The supported keys for collection requirement entries are ``name``, ``version``, ``source``,…
961 msgid "The ``version`` key can take in the same range identifier format documented above. If you're…
965 msgid "The ``type`` key can be set to ``galaxy``, ``url``, ``file``, and ``git``. If ``type`` is om…
969 msgid "Roles can also be specified and placed under the ``roles`` key. The values follow the same f…
973 msgid "To install both roles and collections at the same time with one command, run the following:"
977 msgid "Running ``ansible-galaxy collection install -r`` or ``ansible-galaxy role install -r`` will …
981 msgid "Installing both roles and collections from the same requirements file will not work when spe…
985 msgid "Downloading a collection for offline use"
989 msgid "To download the collection tarball from Galaxy for offline use:"
993 msgid "Navigate to the collection page."
997 msgid "Click on :guilabel:`Download tarball`."
1001 msgid "You may also need to manually download any dependent collections."
1005 msgid "Configuring the ``ansible-galaxy`` client"
1009 msgid "By default, ``ansible-galaxy`` uses https://galaxy.ansible.com as the Galaxy server (as list…
1013 msgid "You can use either option below to configure ``ansible-galaxy collection`` to use other serv…
1017 msgid "Set the server list in the :ref:`galaxy_server_list` configuration option in :ref:`ansible_c…
1021 msgid "Use the ``--server`` command line argument to limit to an individual server."
1025 msgid "To configure a Galaxy server list in ``ansible.cfg``:"
1029 msgid "Add the ``server_list``  option under the ``[galaxy]`` section to one or more server names."
1033 msgid "Create a new section for each server name."
1037 msgid "Set the ``url`` option for each server name."
1041 msgid "Optionally, set the API token for each server name. Go to https://galaxy.ansible.com/me/pref…
1045 msgid "The ``url`` option for each server name must end with a forward slash ``/``. If you do not s…
1049 msgid "For Automation Hub, you additionally need to:"
1053 msgid "Set the ``auth_url`` option for each server name."
1057 msgid "Set the API token for each server name. Go to https://cloud.redhat.com/ansible/automation-hu…
1061 msgid "The following example shows how to configure multiple servers:"
1065 msgid "You can use the ``--server`` command line argument to select an explicit Galaxy server in th…
1069 msgid "**Galaxy server list configuration options**"
1073 msgid "The :ref:`galaxy_server_list` option is a list of server identifiers in a prioritized order.…
1077 msgid "``url``: The URL of the Galaxy instance to connect to. Required."
1081 msgid "``token``: An API token key to use for authentication against the Galaxy instance. Mutually …
1085 msgid "``username``: The username to use for basic authentication against the Galaxy instance. Mutu…
1089 msgid "``password``: The password to use, in conjunction with ``username``, for basic authenticatio…
1093 msgid "``auth_url``: The URL of a Keycloak server 'token_endpoint' if using SSO authentication (for…
1097 msgid "As well as defining these server options in the ``ansible.cfg`` file, you can also define th…
1101 msgid "For operations that use only one Galaxy server (for example, the ``publish``, ``info``, or `…
1105 msgid "Once a collection is found, any of its requirements are only searched within the same Galaxy…
1109 msgid "Downloading collections"
1113 msgid "To download a collection and its dependencies for an offline install, run ``ansible-galaxy c…
1117 msgid "Just like the ``install`` command, the collections are sourced based on the :ref:`configured…
1121 msgid "Collections can be specified as one or multiple collections or with a ``requirements.yml`` f…
1125 msgid "To download a single collection and its dependencies:"
1129 msgid "To download a single collection at a specific version:"
1133 msgid "To download multiple collections either specify multiple collections as command line argumen…
1137 msgid "You can also download a source collection directory. The collection is built with the mandat…
1141 msgid "You can download multiple source collections from a single namespace by providing the path t…
1145 msgid "All the collections are downloaded by default to the ``./collections`` folder but you can us…
1149 msgid "Once you have downloaded the collections, the folder contains the collections specified, the…
1153 msgid "Listing collections"
1157 msgid "To list installed collections, run ``ansible-galaxy collection list``. This shows all of the…
1161 msgid "Run with ``-vvv`` to display more detailed information."
1165 msgid "To list a specific collection, pass a valid fully qualified collection name (FQCN) to the co…
1169 msgid "To search other paths for collections, use the ``-p`` option. Specify multiple search paths …
1173 msgid "Verifying collections"
1177 msgid "Verifying collections with ``ansible-galaxy``"
1181 msgid "Once installed, you can verify that the content of the installed collection matches the cont…
1185 msgid "The output of the ``ansible-galaxy collection verify`` command is quiet if it is successful.…
1189 msgid "You can use the ``-vvv`` flag to display additional information, such as the version and pat…
1193 msgid "If you have a pre-release or non-latest version of a collection installed you should include…
1197 msgid "In addition to the ``namespace.collection_name:version`` format, you can provide the collect…
1201 msgid "Verifying against ``tar.gz`` files is not supported. If your ``requirements.yml`` contains p…
1205 msgid "Using collections in a Playbook"
1209 msgid "Once installed, you can reference a collection content by its fully qualified collection nam…
1213 msgid "This works for roles or any type of plugin distributed within the collection:"
1217 msgid "Simplifying module names with the ``collections`` keyword"
1221 msgid "The ``collections`` keyword lets you define a list of collections that your role or playbook…
1225 msgid "If your playbook uses both the ``collections`` keyword and one or more roles, the roles do n…
1229 msgid "Using ``collections`` in roles"
1233 msgid "Within a role, you can control which collections Ansible searches for the tasks inside the r…
1237 msgid "Using ``collections`` in playbooks"
1241 msgid "In a playbook, you can control the collections Ansible searches for modules and action plugi…
1245 msgid "The ``collections`` keyword merely creates an ordered 'search path' for non-namespaced plugi…
1249 msgid "Using a playbook from a collection"
1253 msgid "You can also distribute playbooks in your collection and invoke them using the same semantic…
1257 msgid "From inside a playbook:"
1261 msgid "A few recommendations when creating such playbooks, ``hosts:`` should be generic or at least…
1265 msgid "This will have an implied entry in the ``collections:`` keyword of ``my_namespace.my_collect…
1269 msgid ":ref:`developing_collections`"
1273 msgid "Develop or modify a collection."
1277 msgid ":ref:`collections_galaxy_meta`"
1281 msgid "Understand the collections metadata structure."
1285 msgid "`Mailing List <https://groups.google.com/group/ansible-devel>`_"
1289 msgid "The development mailing list"
1293 msgid "Working with command line tools"
1297 msgid "Most users are familiar with `ansible` and `ansible-playbook`, but those are not the only ut…
1301 msgid "Data manipulation"
1305 msgid "In many cases, you need to do some complex operation with your variables, while Ansible is n…
1309 msgid "Let's start with a quick definition of each type of plugin:"
1313 msgid "lookups: Mainly used to query 'external data', in Ansible these were the primary part of loo…
1317 msgid "filters: used to change/transform data, used with the ``|`` Jinja2 operator."
1321 msgid "tests: used to validate data, used with the ``is`` Jinja2 operator."
1325 msgid "Loops and list comprehensions"
1329 msgid "Most programming languages have loops (``for``, ``while``, and so on) and list comprehension…
1333 msgid "map: this is a basic for loop that just allows you to change every item in a list, using the…
1337 msgid "select/reject: this is a for loop with a condition, that allows you to create a subset of a …
1341 msgid "selectattr/rejectattr: very similar to the above but it uses a specific attribute of the lis…
1345 msgid "Use a loop to create exponential backoff for retries/until."
1349 msgid "Extract keys from a dictionary matching elements from a list"
1353 msgid "The Python equivalent code would be:"
1357 msgid "There are several ways to do it in Ansible, this is just one example:"
1361 msgid "Way to extract matching keys from a list of dictionaries"
1365 msgid "Results of debug task, a list with the extracted keys"
1369 msgid "Get the unique list of values of a variable that vary per host"
1373 msgid "Find mount point"
1377 msgid "In this case, we want to find the mount point for a given path across our machines, since we…
1381 msgid "Use selectattr to filter mounts into list I can then sort and select the last from"
1385 msgid "Omit elements from a list"
1389 msgid "The special ``omit`` variable ONLY works with module options, but we can still use it in oth…
1393 msgid "Inline list filtering when feeding a module option"
1397 msgid "Another way is to avoid adding elements to the list in the first place, so you can just use …
1401 msgid "Using set_fact in a loop to increment a list conditionally"
1405 msgid "Combine values from same list of dicts"
1409 msgid "Combining positive and negative filters from examples above, you can get a 'value when it ex…
1413 msgid "Use selectattr and rejectattr to get the ansible_host or inventory_hostname as needed"
1417 msgid "Custom Fileglob Based on a Variable"
1421 msgid "This example uses `Python argument list unpacking <https://docs.python.org/3/tutorial/contro…
1425 msgid "Using fileglob with a list based on a variable."
1429 msgid "Complex Type transformations"
1433 msgid "Jinja provides filters for simple data type transformations (``int``, ``bool``, and so on), …
1437 msgid "Create dictionary from list"
1441 msgid "In most languages it is easy to create a dictionary (a.k.a. map/associative array/hash and s…
1445 msgid "These example produces ``{\"a\": \"b\", \"c\": \"d\"}``"
1449 msgid "Simple list to dict by assuming the list is [key, value , key, value, ...]"
1453 msgid "It is simpler when we have a list of pairs:"
1457 msgid "Both end up being the same thing, with ``slice(2)`` transforming ``single_list`` to a ``list…
1461 msgid "A bit more complex, using ``set_fact`` and a ``loop`` to create/update a dictionary with key…
1465 msgid "Using set_fact to create a dictionary from a set of lists"
1469 msgid "This results in ``{\"foo\": \"a\", \"var\": \"b\", \"bar\": \"c\"}``."
1473 msgid "You can even combine these simple examples with other filters and lookups to create a dictio…
1477 msgid "Using 'vars' to define dictionary from a set of lists without needing a task"
1481 msgid "A quick explanation, since there is a lot to unpack from these two lines:"
1485 msgid "The ``varnames`` lookup returns a list of variables that match \"begin with ``my``\"."
1489 msgid "Then feeding the list from the previous step into the ``vars`` lookup to get the list of val…
1493 msgid "Both lists get passed to the ``zip`` filter to pair them off into a unified list (key, value…
1497 msgid "The dict function then takes this 'list of pairs' to create the dictionary."
1501 msgid "An example on how to use facts to find a host's data that meets condition X:"
1505 msgid "Using an example from @zoradache on reddit, to show the 'uptime in days/hours/minutes' (assu…
1509 msgid ":doc:`playbooks_filters`"
1513 msgid "Jinja2 filters included with Ansible"
1517 msgid ":doc:`playbooks_tests`"
1521 msgid "Jinja2 tests included with Ansible"
1525 msgid "`Jinja2 Docs <https://jinja.palletsprojects.com/>`_"
1529 msgid "Jinja2 documentation, includes lists for core filters and tests"
1533 msgid "Connection methods and details"
1537 msgid "This section shows you how to expand and refine the connection methods Ansible uses for your…
1541 msgid "ControlPersist and paramiko"
1545 msgid "By default, Ansible uses native OpenSSH, because it supports ControlPersist (a performance f…
1549 msgid "Setting a remote user"
1553 msgid "By default, Ansible connects to all remote devices with the user name you are using on the c…
1557 msgid "as a host variable in inventory:"
1561 msgid "or as a group variable in inventory:"
1565 msgid "Setting up SSH keys"
1569 msgid "By default, Ansible assumes you are using SSH keys to connect to remote machines.  SSH keys …
1573 msgid "Ansible does not expose a channel to allow communication between the user and the ssh proces…
1577 msgid "To set up SSH agent to avoid retyping passwords, you can do:"
1581 msgid "Depending on your setup, you may wish to use Ansible's ``--private-key`` command line option…
1585 msgid "Another way to add private key files without using ssh-agent is using ``ansible_ssh_private_…
1589 msgid "Running against localhost"
1593 msgid "You can run commands against the control node by using \"localhost\" or \"127.0.0.1\" for th…
1597 msgid "You can specify localhost explicitly by adding this to your inventory file:"
1601 msgid "Managing host key checking"
1605 msgid "Ansible enables host key checking by default. Checking host keys guards against server spoof…
1609 msgid "If a host is reinstalled and has a different key in 'known_hosts', this will result in an er…
1613 msgid "If you understand the implications and wish to disable this behavior, you can do so by editi…
1617 msgid "Alternatively this can be set by the :envvar:`ANSIBLE_HOST_KEY_CHECKING` environment variabl…
1621 msgid "Also note that host key checking in paramiko mode is reasonably slow, therefore switching to…
1625 msgid "Other connection methods"
1629 msgid "Ansible can use a variety of connection methods beyond SSH. You can select any connection pl…
1633 msgid "Playbook Example: Continuous Delivery and Rolling Upgrades"
1637 msgid "What is continuous delivery?"
1641 msgid "Continuous delivery (CD) means frequently delivering updates to your software application."
1645 msgid "The idea is that by updating more often, you do not have to wait for a specific timed period…
1649 msgid "Some Ansible users are deploying updates to their end users on an hourly or even more freque…
1653 msgid "This document describes in detail how to achieve this goal, using one of Ansible's most comp…
1657 msgid "`Click here for the latest playbooks for this example <https://github.com/ansible/ansible-ex…
1661 msgid "The playbooks deploy Apache, PHP, MySQL, Nagios, and HAProxy to a CentOS-based set of server…
1665 msgid "We're not going to cover how to run these playbooks here. Read the included README in the gi…
1669 msgid "Site deployment"
1673 msgid "Let's start with ``site.yml``. This is our site-wide deployment playbook. It can be used to …
1677 msgid "If you're not familiar with terms like playbooks and plays, you should review :ref:`working_…
1681 msgid "In this playbook we have 5 plays. The first one targets ``all`` hosts and applies the ``comm…
1685 msgid "The next four plays run against specific host groups and apply specific roles to those serve…
1689 msgid "Reusable content: roles"
1693 msgid "By now you should have a bit of understanding about roles and how they work in Ansible. Role…
1697 msgid "This example has six roles: ``common``, ``base-apache``, ``db``, ``haproxy``, ``nagios``, an…
1701 msgid "Roles can have variables and dependencies, and you can pass in parameters to roles to modify…
1705 msgid "Configuration: group variables"
1709 msgid "Group variables are variables that are applied to groups of servers. They can be used in tem…
1713 msgid "This is a YAML file, and you can create lists and dictionaries for more complex variable str…
1717 msgid "Here's another group variables file. This is ``group_vars/dbservers`` which applies to the h…
1721 msgid "If you look in the example, there are group variables for the ``webservers`` group and the `…
1725 msgid "These variables are used in a variety of places. You can use them in playbooks, like this, i…
1729 msgid "You can also use these variables in templates, like this, in ``roles/common/templates/ntp.co…
1733 msgid "You can see that the variable substitution syntax of {{ and }} is the same for both template…
1737 msgid "This is testing to see if the inventory name of the machine we're currently operating on (``…
1741 msgid "Here's another example, from the same template:"
1745 msgid "This loops over all of the hosts in the group called ``monitoring``, and adds an ACCEPT line…
1749 msgid "You can learn a lot more about Jinja2 and its capabilities `here <https://jinja.palletsproje…
1753 msgid "The rolling upgrade"
1757 msgid "Now you have a fully-deployed site with web servers, a load balancer, and monitoring. How do…
1761 msgid "Ansible has the capability to do operations on multi-tier applications in a coordinated way,…
1765 msgid "Looking at the playbook, you can see it is made up of two plays. The first play is very simp…
1769 msgid "What's going on here, and why are there no tasks? You might know that Ansible gathers \"fact…
1773 msgid "The next part is the update play. The first part looks like this:"
1777 msgid "This is just a normal play definition, operating on the ``webservers`` group. The ``serial``…
1781 msgid "Here is the next part of the update play:"
1785 msgid "The ``serial`` keyword forces the play to be executed in 'batches'. Each batch counts as a f…
1789 msgid "The ``pre_tasks`` keyword just lets you list tasks to run before the roles are called. This …
1793 msgid "The ``delegate_to`` and ``loop`` arguments, used together, cause Ansible to loop over each m…
1797 msgid "Note that the HAProxy step looks a little complicated.  We're using HAProxy in this example …
1801 msgid "The next step simply re-applies the proper roles to the web servers. This will cause any con…
1805 msgid "Finally, in the ``post_tasks`` section, we reverse the changes to the Nagios configuration a…
1809 msgid "Again, if you were using a Netscaler or F5 or Elastic Load Balancer, you would just substitu…
1813 msgid "Managing other load balancers"
1817 msgid "In this example, we use the simple HAProxy load balancer to front-end the web servers. It's …
1821 msgid "For other load balancers, you may need to send shell commands to them (like we do for HAProx…
1825 msgid "Continuous delivery end-to-end"
1829 msgid "Now that you have an automated way to deploy updates to your application, how do you tie it …
1833 msgid "Depending on your environment, you might be deploying continuously to a test environment, ru…
1837 msgid "For integration with Continuous Integration systems, you can easily trigger playbook runs us…
1841 msgid "This should give you a good idea of how to structure a multi-tier application with Ansible, …
1845 msgid "`lamp_haproxy example <https://github.com/ansible/ansible-examples/tree/master/lamp_haproxy>…
1849 msgid "The lamp_haproxy example discussed here."
1868 msgid ":ref:`working_with_playbooks`"
1895 msgid "An introduction to playbooks"
1909 msgid ":ref:`playbooks_reuse_roles`"
1913 msgid "An introduction to playbook roles"
1929 msgid ":ref:`playbooks_variables`"
1933 msgid "An introduction to Ansible variables"
1937 msgid "`Ansible.com: Continuous Delivery <https://www.ansible.com/use-cases/continuous-delivery>`_"
1941 msgid "An introduction to Continuous Delivery with Ansible"
1945 msgid "User Guide"
1949 msgid "**Making Open Source More Inclusive**"
1953 msgid "Red Hat is committed to replacing problematic language in our code, documentation, and web p…
1957 msgid "Welcome to the Ansible User Guide! This guide covers how to work with Ansible, including usi…
1961 msgid "Getting started"
1965 msgid "I'd like an overview of how Ansible works. Where can I find:"
1969 msgid "a :ref:`quick video overview <quickstart_guide>`"
1973 msgid "a :ref:`text introduction <intro_getting_started>`"
1977 msgid "I'm ready to learn about Ansible. What :ref:`basic_concepts` do I need to learn?"
1981 msgid "I want to use Ansible without writing a playbook. How do I use :ref:`ad hoc commands <intro_…
1985 msgid "Writing tasks, plays, and playbooks"
1989 msgid "I'm writing my first playbook. What should I :ref:`know before I begin <playbooks_tips_and_t…
1993 msgid "I have a specific use case for a task or play:"
1997 msgid "Executing tasks with elevated privileges or as a different user with :ref:`become <become>`"
2001 msgid "Repeating a task once for each item in a list with :ref:`loops <playbooks_loops>`"
2005 msgid "Executing tasks on a different machine with :ref:`delegation <playbooks_delegation>`"
2009 msgid "Running tasks only when certain conditions apply with :ref:`conditionals <playbooks_conditio…
2013 msgid "Grouping a set of tasks together with :ref:`blocks <playbooks_blocks>`"
2017 msgid "Running tasks only when something has changed with :ref:`handlers <handlers>`"
2021 msgid "Changing the way Ansible :ref:`handles failures <playbooks_error_handling>`"
2025 msgid "Setting remote :ref:`environment values <playbooks_environment>`"
2029 msgid "I want to leverage the power of re-usable Ansible artifacts. How do I create re-usable :ref:…
2033 msgid "I need to incorporate one file or playbook inside another. What is the difference between :r…
2037 msgid "I want to run selected parts of my playbook. How do I add and use :ref:`tags <tags>`?"
2041 msgid "Working with inventory"
2045 msgid "I have a list of servers and devices I want to automate. How do I create :ref:`inventory <in…
2049 msgid "I use cloud services and constantly have servers and devices starting and stopping. How do I…
2053 msgid "I want to automate specific sub-sets of my inventory. How do I use :ref:`patterns <intro_pat…
2057 msgid "Interacting with data"
2061 msgid "I want to use a single playbook against multiple systems with different attributes. How do I…
2065 msgid "I want to retrieve data about my systems. How do I access :ref:`Ansible facts <vars_and_fact…
2069 msgid "I need to access sensitive data like passwords with Ansible. How can I protect that data wit…
2073 msgid "I want to change the data I have, so I can use it in a task. How do I use :ref:`filters <pla…
2077 msgid "I need to retrieve data from an external datastore. How do I use :ref:`lookups <playbooks_lo…
2081 msgid "I want to ask playbook users to supply data. How do I get user input with :ref:`prompts <pla…
2085 msgid "I use certain modules frequently. How do I streamline my inventory and playbooks by :ref:`se…
2089 msgid "Executing playbooks"
2093 msgid "Once your playbook is ready to run, you may need to use these topics:"
2097 msgid "Executing \"dry run\" playbooks with :ref:`check mode and diff <check_mode_dry>`"
2101 msgid "Running playbooks while troubleshooting with :ref:`start and step <playbooks_start_and_step>…
2105 msgid "Correcting tasks during execution with the :ref:`Ansible debugger <playbook_debugger>`"
2109 msgid "Controlling how my playbook executes with :ref:`strategies and more <playbooks_strategies>`"
2113 msgid "Running tasks, plays, and playbooks :ref:`asynchronously <playbooks_async>`"
2117 msgid "Advanced features and reference"
2121 msgid "Using :ref:`advanced syntax <playbooks_advanced_syntax>`"
2125 msgid "Manipulating :ref:`complex data <complex_data_manipulation>`"
2129 msgid "Using :ref:`plugins <plugins_lookup>`"
2133 msgid "Using :ref:`playbook keywords <playbook_keywords>`"
2137 msgid "Using :ref:`command-line tools <command_line_tools>`"
2141 msgid "Rejecting :ref:`specific modules <plugin_filtering_config>`"
2145 msgid "Module :ref:`maintenance <modules_support>`"
2149 msgid "Traditional Table of Contents"
2153 msgid "If you prefer to read the entire User Guide, here's a list of the pages in order:"
2157 msgid "Introduction"
2161 msgid "Before we start exploring the main components of Ansible -- playbooks, configuration managem…
2165 msgid "Introduction to ad hoc commands"
2169 msgid "An Ansible ad hoc command uses the `/usr/bin/ansible` command-line tool to automate a single…
2173 msgid "Why use ad hoc commands?"
2177 msgid "ad hoc commands are great for tasks you repeat rarely. For example, if you want to power off…
2181 msgid "You can learn more about :ref:`patterns<intro_patterns>` and :ref:`modules<working_with_modu…
2185 msgid "Use cases for ad hoc tasks"
2189 msgid "ad hoc tasks can be used to reboot servers, copy files, manage packages and users, and much …
2193 msgid "Rebooting servers"
2197 msgid "The default module for the ``ansible`` command-line utility is the :ref:`ansible.builtin.com…
2201 msgid "By default Ansible uses only 5 simultaneous processes. If you have more hosts than the value…
2205 msgid "/usr/bin/ansible will default to running from your user account. To connect as a different u…
2209 msgid "Rebooting probably requires privilege escalation. You can connect to the server as ``usernam…
2213 msgid "If you add ``--ask-become-pass`` or ``-K``, Ansible prompts you for the password to use for …
2217 msgid "The :ref:`command module <command_module>` does not support extended shell syntax like pipin…
2221 msgid "So far all our examples have used the default 'command' module. To use a different module, p…
2225 msgid "When running any command with the Ansible *ad hoc* CLI (as opposed to :ref:`Playbooks <worki…
2229 msgid "Managing files"
2233 msgid "An ad hoc task can harness the power of Ansible and SCP to transfer many files to multiple m…
2237 msgid "If you plan to repeat a task like this, use the :ref:`ansible.builtin.template<template_modu…
2241 msgid "The :ref:`ansible.builtin.file<file_module>` module allows changing ownership and permission…
2245 msgid "The ``file`` module can also create directories, similar to ``mkdir -p``:"
2249 msgid "As well as delete directories (recursively) and delete files:"
2253 msgid "Managing packages"
2257 msgid "You might also use an ad hoc task to install, update, or remove packages on managed nodes us…
2261 msgid "To ensure a specific version of a package is installed:"
2265 msgid "To ensure a package is at the latest version:"
2269 msgid "To ensure a package is not installed:"
2273 msgid "Ansible has modules for managing packages under many platforms. If there is no module for yo…
2277 msgid "Managing users and groups"
2281 msgid "You can create, manage, and remove user accounts on your managed nodes with ad hoc tasks:"
2285 msgid "See the :ref:`ansible.builtin.user <user_module>` module documentation for details on all of…
2289 msgid "Managing services"
2293 msgid "Ensure a service is started on all webservers:"
2297 msgid "Alternatively, restart a service on all webservers:"
2301 msgid "Ensure a service is stopped:"
2305 msgid "Gathering facts"
2309 msgid "Facts represent discovered variables about a system. You can use facts to implement conditio…
2313 msgid "You can also filter this output to display only certain facts, see the :ref:`ansible.builtin…
2317 msgid "Now that you understand the basic elements of Ansible execution, you are ready to learn to a…
2321 msgid ":ref:`intro_configuration`"
2325 msgid "All about the Ansible config file"
2334 msgid ":ref:`list_of_collections`"
2343 msgid "Browse existing collections, modules, and plugins"
2347 msgid "Using Ansible for configuration management & deployment"
2365 msgid "`Mailing List <https://groups.google.com/group/ansible-project>`_"
2369 msgid "Ansible and BSD"
2373 msgid "Managing BSD machines is different from managing other Unix-like machines. If you have manag…
2377 msgid "Connecting to BSD nodes"
2381 msgid "Ansible connects to managed nodes using OpenSSH by default. This works on BSD if you use SSH…
2385 msgid "Bootstrapping BSD"
2389 msgid "Ansible is agentless by default, however, it requires Python on managed nodes. Only the :ref…
2393 msgid "The following example installs Python 2.7 which includes the json library required for full …
2397 msgid "Or for OpenBSD:"
2401 msgid "Once this is done you can now use other Ansible modules apart from the ``raw`` module."
2405 msgid "This example demonstrated using pkg on FreeBSD and pkg_add on OpenBSD, however you should be…
2409 msgid "Setting the Python interpreter"
2413 msgid "To support a variety of Unix-like operating systems and distributions, Ansible cannot always…
2417 msgid "If you use additional plugins beyond those bundled with Ansible, you can set similar variabl…
2421 msgid "Which modules are available?"
2425 msgid "The majority of the core Ansible modules are written for a combination of Unix-like machines…
2429 msgid "Using BSD as the control node"
2433 msgid "Using BSD as the control machine is as simple as installing the Ansible package for your BSD…
2437 msgid "BSD facts"
2441 msgid "Ansible gathers facts from the BSDs in a similar manner to Linux machines, but since the dat…
2445 msgid "BSD efforts and contributions"
2449 msgid "BSD support is important to us at Ansible. Even though the majority of our contributors use …
2459 msgid ":ref:`intro_adhoc`"
2466 msgid "Examples of basic commands"
2470 msgid "Learning ansible's configuration management language"
2480 msgid ":ref:`developing_modules`"
2484 msgid "How to write modules"
2488 msgid "Working with dynamic inventory"
2492 msgid "If your Ansible inventory fluctuates over time, with hosts spinning up and shutting down in …
2496 msgid "Ansible integrates all of these options through a dynamic external inventory system. Ansible…
2500 msgid "Inventory plugins take advantage of the most recent updates to the Ansible core code. We rec…
2504 msgid "You can still use inventory scripts if you choose. When we implemented inventory plugins, we…
2508 msgid "If you prefer a GUI for handling dynamic inventory, the :ref:`ansible_tower` inventory datab…
2512 msgid "Inventory script example: Cobbler"
2516 msgid "Ansible integrates seamlessly with `Cobbler <https://cobbler.github.io>`_, a Linux installat…
2520 msgid "While primarily used to kickoff OS installations and manage DHCP and DNS, Cobbler has a gene…
2524 msgid "To tie your Ansible inventory to Cobbler, copy `this script <https://raw.githubusercontent.c…
2528 msgid "Add a ``cobbler.ini`` file in ``/usr/local/etc/ansible`` so Ansible knows where the Cobbler …
2532 msgid "First test the script by running ``/usr/local/etc/ansible/cobbler.py`` directly. You should …
2536 msgid "Let's explore what this does.  In Cobbler, assume a scenario somewhat like the following:"
2540 msgid "In the example above, the system 'foo.example.com' is addressable by ansible directly, but i…
2544 msgid "The script provides more than host and group info. In addition, as a bonus, when the 'setup'…
2548 msgid "Which could be executed just like this:"
2552 msgid "The name 'webserver' came from Cobbler, as did the variables for the config file.  You can s…
2556 msgid "So, with the template above (``motd.j2``), this results in the following data being written …
2560 msgid "And on system 'bar' (bar.example.com):"
2564 msgid "And technically, though there is no major good reason to do it, this also works:"
2568 msgid "So, in other words, you can use those variables in arguments/actions as well."
2572 msgid "Inventory script example: OpenStack"
2576 msgid "If you use an OpenStack-based cloud, instead of manually maintaining your own inventory file…
2580 msgid "You can download the latest version of the OpenStack inventory script `here <https://raw.git…
2584 msgid "You can use the inventory script explicitly (by passing the `-i openstack_inventory.py` argu…
2588 msgid "Explicit use of OpenStack inventory script"
2592 msgid "Download the latest version of the OpenStack dynamic inventory script and make it executable…
2596 msgid "Do not name it `openstack.py`. This name will conflict with imports from openstacksdk."
2600 msgid "Source an OpenStack RC file:"
2604 msgid "An OpenStack RC file contains the environment variables required by the client tools to esta…
2608 msgid "You can confirm the file has been successfully sourced by running a simple command, such as …
2612 msgid "The OpenStack command line clients are required to run the `nova list` command. For more inf…
2616 msgid "You can test the OpenStack dynamic inventory script manually to confirm it is working as exp…
2621 msgid "After a few moments you should see some JSON output with information about your compute inst…
2625 msgid "Once you confirm the dynamic inventory script is working as expected, you can tell Ansible t…
2629 msgid "Implicit use of OpenStack inventory script"
2633 msgid "Download the latest version of the OpenStack dynamic inventory script, make it executable an…
2637 msgid "Download the sample configuration file, modify it to suit your needs and copy it to `/usr/lo…
2641 msgid "You can test the OpenStack dynamic inventory script manually to confirm it is working as exp…
2645 msgid "Refreshing the cache"
2649 msgid "Note that the OpenStack dynamic inventory script will cache results to avoid repeated API ca…
2653 msgid "Other inventory scripts"
2657 msgid "In Ansible 2.10 and later, inventory scripts moved to their associated collections. Many are…
2661 msgid "Using inventory directories and multiple inventory sources"
2665 msgid "If the location given to ``-i`` in Ansible is a directory (or as so configured in ``ansible.…
2669 msgid "In an inventory directory, executable files are treated as dynamic inventory sources and mos…
2673 msgid "You can replace this list with your own selection by configuring an ``inventory_ignore_exten…
2677 msgid "Any ``group_vars`` and ``host_vars`` subdirectories in an inventory directory are interprete…
2681 msgid "Static groups of dynamic groups"
2685 msgid "When defining groups of groups in the static inventory file, the child groups must also be d…
2690 msgid ":ref:`intro_inventory`"
2694 msgid "All about static inventory files"
2698 msgid "Getting Started"
2702 msgid "Now that you have read the :ref:`installation guide<installation_guide>` and installed Ansib…
2706 msgid "selects machines to execute against from inventory"
2710 msgid "connects to those machines (or network devices, or other managed nodes), usually over SSH"
2714 msgid "copies one or more modules to the remote machines and starts execution there"
2718 msgid "Ansible can do much more, but you should understand the most common use case before explorin…
2722 msgid "Selecting machines from inventory"
2726 msgid "Ansible reads information about which machines you want to manage from your inventory. Altho…
2730 msgid "Action: create a basic inventory"
2734 msgid "For this basic inventory, edit (or create) ``/usr/local/etc/ansible/hosts`` and add a few re…
2740 msgid "Beyond the basics"
2744 msgid "Your inventory can store much more than IPs and FQDNs. You can create :ref:`aliases<inventor…
2748 msgid "Connecting to remote nodes"
2752 msgid "Ansible communicates with remote machines over the `SSH protocol <https://www.ssh.com/ssh/pr…
2756 msgid "Action: check your SSH connections"
2760 msgid "Confirm that you can connect using SSH to all the nodes in your inventory using the same use…
2764 msgid "You can override the default remote user name in several ways, including:"
2768 msgid "passing the ``-u`` parameter at the command line"
2772 msgid "setting user information in your inventory file"
2776 msgid "setting user information in your configuration file"
2780 msgid "setting environment variables"
2784 msgid "See :ref:`general_precedence_rules` for details on the (sometimes unintuitive) precedence of…
2788 msgid "Copying and executing modules"
2792 msgid "Once it has connected, Ansible transfers the modules required by your command or playbook to…
2796 msgid "Action: run your first Ansible commands"
2800 msgid "Use the ping module to ping all the nodes in your inventory:"
2805 msgid "You should see output for each host in your inventory, similar to this:"
2809 msgid "You can use ``-u`` as one way to specify the user to connect as, by default Ansible uses SSH…
2813 msgid "Now run a live command on all of your nodes:"
2817 msgid "Action: Run your first playbook"
2821 msgid "Playbooks are used to pull together tasks into reusable units."
2825 msgid "Ansible does not store playbooks for you; they are simply YAML documents that you store and …
2829 msgid "In a directory of your choice you can create your first playbook in a file called mytask.yml…
2833 msgid "You can run this command as follows:"
2837 msgid "and may see output like this:"
2841 msgid "Read on to learn more about controlling which nodes your playbooks execute on, more sophisti…
2845 msgid "By default Ansible uses SFTP to transfer files. If the machine or device you want to manage …
2849 msgid "If you need privilege escalation (sudo and similar) to run a command, pass the ``become`` fl…
2853 msgid "You can read more about privilege escalation in :ref:`become`."
2857 msgid "Congratulations! You have contacted your nodes using Ansible. You used a basic inventory fil…
2861 msgid "Resources"
2865 msgid "`Product Demos <https://github.com/ansible/product-demos>`_"
2869 msgid "`Katakoda <https://katacoda.com/rhel-labs>`_"
2873 msgid "`Workshops <https://github.com/ansible/workshops>`_"
2877 msgid "`Ansible Examples <https://github.com/ansible/ansible-examples>`_"
2881 msgid "`Ansible Baseline <https://github.com/ansible/ansible-baseline>`_"
2885 msgid "Next steps"
2889 msgid "Next you can read about more real-world cases in :ref:`intro_adhoc`, explore what you can do…
2893 msgid "More information about inventory"
2897 msgid "Learning Ansible's configuration management language"
2901 msgid "`Ansible Demos <https://github.com/ansible/product-demos>`_"
2905 msgid "Demonstrations of different Ansible usecases"
2909 msgid "`RHEL Labs <https://katacoda.com/rhel-labs>`_"
2913 msgid "Labs to provide further knowledge on different topics"
2917 msgid "How to build your inventory"
2921 msgid "Ansible works against multiple managed nodes or \"hosts\" in your infrastructure at the same…
2925 msgid "The default location for inventory is a file called ``/usr/local/etc/ansible/hosts``. You ca…
2929 msgid "Inventory basics: formats, hosts, and groups"
2933 msgid "The inventory file can be in one of many formats, depending on the inventory plugins you hav…
2937 msgid "The headings in brackets are group names, which are used in classifying hosts and deciding w…
2941 msgid "Here's that same basic inventory file in YAML format:"
2945 msgid "Default groups"
2949 msgid "There are two default groups: ``all`` and ``ungrouped``. The ``all`` group contains every ho…
2953 msgid "Hosts in multiple groups"
2957 msgid "You can (and probably will) put each host in more than one group. For example a production w…
2961 msgid "What - An application, stack or microservice (for example, database servers, web servers, an…
2965 msgid "Where - A datacenter or region, to talk to local DNS, storage, and so on (for example, east,…
2969 msgid "When - The development stage, to avoid testing on production resources (for example, prod, t…
2973 msgid "Extending the previous YAML inventory to include what, when, and where would look like:"
2977 msgid "You can see that ``one.example.com`` exists in the ``dbservers``, ``east``, and ``prod`` gro…
2981 msgid "You can also use nested groups to simplify ``prod`` and ``test`` in this inventory, for the …
2985 msgid "You can find more examples on how to organize your inventories and group your hosts in :ref:…
2989 msgid "Adding ranges of hosts"
2993 msgid "If you have a lot of hosts with a similar pattern, you can add them as a range rather than l…
3000 msgid "In INI:"
3009 msgid "In YAML:"
3013 msgid "You can specify a stride (increments between sequence numbers) when defining a numeric range…
3017 msgid "For numeric patterns, leading zeros can be included or removed, as desired. Ranges are inclu…
3021 msgid "Adding variables to inventory"
3025 msgid "You can store variable values that relate to a specific host or group in inventory. To start…
3029 msgid "Assigning a variable to one machine: host variables"
3033 msgid "You can easily assign a variable to a single host, then use it later in playbooks. In INI:"
3037 msgid "Unique values like non-standard SSH ports work well as host variables. You can add them to y…
3041 msgid "Connection variables also work well as host variables:"
3045 msgid "If you list non-standard SSH ports in your SSH config file, the ``openssh`` connection will …
3049 msgid "Inventory aliases"
3053 msgid "You can also define aliases in your inventory:"
3057 msgid "In the above example, running Ansible against the host alias \"jumper\" will connect to 192.…
3061 msgid "Values passed in the INI format using the ``key=value`` syntax are interpreted differently d…
3065 msgid "When declared inline with the host, INI values are interpreted as Python literal structures …
3069 msgid "When declared in a ``:vars`` section, INI values are interpreted as strings. For example ``v…
3073 msgid "If a variable value set in an INI inventory must be a certain type (for example, a string or…
3077 msgid "Consider using YAML format for inventory sources to avoid confusion on the actual type of a …
3081 msgid "Generally speaking, this is not the best way to define variables that describe your system p…
3085 msgid "Assigning a variable to many machines: group variables"
3089 msgid "If all hosts in a group share a variable value, you can apply that variable to an entire gro…
3093 msgid "Group variables are a convenient way to apply variables to multiple hosts at once. Before ex…
3097 msgid "Inheriting variable values: group variables for groups of groups"
3101 msgid "You can make groups of groups using the ``:children`` suffix in INI or the ``children:`` ent…
3105 msgid "If you need to store lists or hash data, or prefer to keep host and group specific variables…
3109 msgid "Child groups have a couple of properties to note:"
3113 msgid "Any host that is member of a child group is automatically a member of the parent group."
3117 msgid "A child group's variables will have higher precedence (override) a parent group's variables."
3121 msgid "Groups can have multiple parents and children, but not circular relationships."
3125 msgid "Hosts can also be in multiple groups, but there will only be **one** instance of a host, mer…
3129 msgid "Organizing host and group variables"
3133 msgid "Although you can store variables in the main inventory file, storing separate host and group…
3137 msgid "Ansible loads host and group variable files by searching paths relative to the inventory fil…
3141 msgid "For example, if you group hosts in your inventory by datacenter, and each datacenter uses it…
3145 msgid "You can also create *directories* named after your groups or hosts. Ansible will read all th…
3149 msgid "All hosts in the 'raleigh' group will have the variables defined in these files available to…
3153 msgid "You can also add ``group_vars/`` and ``host_vars/`` directories to your playbook directory. …
3157 msgid "Keeping your inventory file and variables in a git repo (or other version control) is an exc…
3161 msgid "How variables are merged"
3165 msgid "By default variables are merged/flattened to the specific host before a play is run. This ke…
3169 msgid "all group (because it is the 'parent' of all other groups)"
3173 msgid "parent group"
3177 msgid "child group"
3181 msgid "host"
3185 msgid "By default Ansible merges groups at the same parent/child level in ASCII order, and the last…
3189 msgid "You can change this behavior by setting the group variable ``ansible_group_priority`` to cha…
3193 msgid "In this example, if both groups have the same priority, the result would normally have been …
3197 msgid "``ansible_group_priority`` can only be set in the inventory source and not in group_vars/, a…
3201 msgid "Using multiple inventory sources"
3205 msgid "You can target multiple inventory sources (directories, dynamic inventory scripts or files s…
3209 msgid "Target two sources from the command line like this:"
3213 msgid "Keep in mind that if there are variable conflicts in the inventories, they are resolved acco…
3217 msgid "**Aggregating inventory sources with a directory**"
3221 msgid "You can also create an inventory by combining multiple inventory sources and source types un…
3225 msgid "You can target this inventory directory simply like this:"
3229 msgid "It can be useful to control the merging order of the inventory sources if there's variable c…
3233 msgid "If ``01-openstack.yml`` defines ``myvar = 1`` for the group ``all``, ``02-dynamic-inventory.…
3237 msgid "For more details on inventory plugins and dynamic inventory scripts see :ref:`inventory_plug…
3241 msgid "Connecting to hosts: behavioral inventory parameters"
3245 msgid "As described above, setting the following variables control how Ansible interacts with remot…
3249 msgid "Host connection:"
3253 msgid "ansible_connection"
3257 msgid "Connection type to the host. This can be the name of any of ansible's connection plugins. SS…
3261 msgid "General for all connections:"
3266 msgid "ansible_host"
3270 msgid "The name of the host to connect to, if different from the alias you wish to give to it."
3274 msgid "ansible_port"
3278 msgid "The connection port number, if not the default (22 for ssh)"
3283 msgid "ansible_user"
3287 msgid "The user name to use when connecting to the host"
3291 msgid "ansible_password"
3295 msgid "The password to use to authenticate to the host (never store this variable in plain text; al…
3299 msgid "Specific to the SSH connection:"
3303 msgid "ansible_ssh_private_key_file"
3307 msgid "Private key file used by ssh.  Useful if using multiple keys and you don't want to use SSH a…
3311 msgid "ansible_ssh_common_args"
3315 msgid "This setting is always appended to the default command line for :command:`sftp`, :command:`s…
3319 msgid "ansible_sftp_extra_args"
3323 msgid "This setting is always appended to the default :command:`sftp` command line."
3327 msgid "ansible_scp_extra_args"
3331 msgid "This setting is always appended to the default :command:`scp` command line."
3335 msgid "ansible_ssh_extra_args"
3339 msgid "This setting is always appended to the default :command:`ssh` command line."
3343 msgid "ansible_ssh_pipelining"
3347 msgid "Determines whether or not to use SSH pipelining. This can override the ``pipelining`` settin…
3351 msgid "ansible_ssh_executable (added in version 2.2)"
3355 msgid "This setting overrides the default behavior to use the system :command:`ssh`. This can overr…
3359 msgid "Privilege escalation (see :ref:`Ansible Privilege Escalation<become>` for further details):"
3363 msgid "Equivalent to ``ansible_sudo`` or ``ansible_su``, allows to force privilege escalation"
3367 msgid "Allows to set privilege escalation method"
3371 msgid "Equivalent to ``ansible_sudo_user`` or ``ansible_su_user``, allows to set the user you becom…
3375 msgid "Equivalent to ``ansible_sudo_password`` or ``ansible_su_password``, allows you to set the pr…
3379 msgid "ansible_become_exe"
3383 msgid "Equivalent to ``ansible_sudo_exe`` or ``ansible_su_exe``, allows you to set the executable f…
3387 msgid "ansible_become_flags"
3391 msgid "Equivalent to ``ansible_sudo_flags`` or ``ansible_su_flags``, allows you to set the flags pa…
3395 msgid "Remote host environment parameters:"
3399 msgid "ansible_shell_type"
3403 msgid "The shell type of the target system. You should not use this setting unless you have set the…
3407 msgid "ansible_python_interpreter"
3411 msgid "The target host python path. This is useful for systems with more than one Python or not loc…
3415 msgid "ansible_*_interpreter"
3419 msgid "Works for anything such as ruby or perl and works just like :ref:`ansible_python_interpreter…
3423 msgid "ansible_shell_executable"
3427 msgid "This sets the shell the ansible controller will use on the target machine, overrides ``execu…
3431 msgid "Examples from an Ansible-INI host file:"
3435 msgid "Non-SSH connection types"
3439 msgid "As stated in the previous section, Ansible executes playbooks over SSH but it is not limited…
3443 msgid "**local**"
3447 msgid "This connector can be used to deploy the playbook to the control machine itself."
3451 msgid "**docker**"
3455 msgid "This connector deploys the playbook directly into Docker containers using the local Docker c…
3459 msgid "The name of the Docker container to connect to."
3463 msgid "The user name to operate within the container. The user must exist inside the container."
3467 msgid "If set to ``true`` the ``become_user`` will be used to operate within the container."
3471 msgid "ansible_docker_extra_args"
3475 msgid "Could be a string with any additional arguments understood by Docker, which are not command …
3479 msgid "Here is an example of how to instantly deploy to created containers:"
3483 msgid "For a full list with available plugins and examples, see :ref:`connection_plugin_list`."
3487 msgid "If you're reading the docs from the beginning, this may be the first example you've seen of …
3491 msgid "Inventory setup examples"
3495 msgid "See also :ref:`sample_setup`, which shows inventory along with playbooks and other Ansible a…
3499 msgid "Example: One inventory per environment"
3503 msgid "If you need to manage multiple environments it's sometimes prudent to have only hosts of a s…
3507 msgid "For the example mentioned above you could have an :file:`inventory_test` file:"
3511 msgid "That file only includes hosts that are part of the \"test\" environment. Define the \"stagin…
3515 msgid "To apply a playbook called :file:`site.yml` to all the app servers in the test environment, …
3519 msgid "Example: Group by function"
3523 msgid "In the previous section you already saw an example for using groups in order to cluster host…
3527 msgid "Example: Group by location"
3531 msgid "Other tasks might be focused on where a certain host is located. Let's say that ``db01.test.…
3535 msgid "In practice, you might even end up mixing all these setups as you might need to, on one day,…
3539 msgid ":ref:`inventory_plugins`"
3543 msgid "Pulling inventory from dynamic or static sources"
3547 msgid ":ref:`intro_dynamic_inventory`"
3551 msgid "Pulling inventory from dynamic sources, such as cloud providers"
3555 msgid "Learning Ansible's configuration, deployment, and orchestration language."
3559 msgid "Patterns: targeting hosts and groups"
3563 msgid "When you execute Ansible through an ad hoc command or by running a playbook, you must choose…
3567 msgid "Using patterns"
3571 msgid "You use a pattern almost any time you execute an ad hoc command or a playbook. The pattern i…
3580 msgid "For example::"
3584 msgid "In a playbook the pattern is the content of the ``hosts:`` line for each play:"
3588 msgid "Since you often want to run a command or playbook against multiple hosts at once, patterns o…
3592 msgid "Common patterns"
3596 msgid "This table lists common patterns for targeting inventory hosts and groups."
3601 msgid "Description"
3605 msgid "Pattern(s)"
3609 msgid "Targets"
3613 msgid "All hosts"
3617 msgid "all (or \\*)"
3621 msgid "One host"
3625 msgid "host1"
3629 msgid "Multiple hosts"
3633 msgid "host1:host2 (or host1,host2)"
3637 msgid "One group"
3641 msgid "webservers"
3645 msgid "Multiple groups"
3649 msgid "webservers:dbservers"
3653 msgid "all hosts in webservers plus all hosts in dbservers"
3657 msgid "Excluding groups"
3661 msgid "webservers:!atlanta"
3665 msgid "all hosts in webservers except those in atlanta"
3669 msgid "Intersection of groups"
3673 msgid "webservers:&staging"
3677 msgid "any hosts in webservers that are also in staging"
3681 msgid "You can use either a comma (``,``) or a colon (``:``) to separate a list of hosts. The comma…
3685 msgid "Once you know the basic patterns, you can combine them. This example::"
3689 msgid "targets all machines in the groups 'webservers' and 'dbservers' that are also in the group '…
3693 msgid "You can use wildcard patterns with FQDNs or IP addresses, as long as the hosts are named in …
3697 msgid "You can mix wildcard patterns and groups at the same time::"
3701 msgid "Limitations of patterns"
3705 msgid "Patterns depend on inventory. If a host or group is not listed in your inventory, you cannot…
3709 msgid "Your pattern must match your inventory syntax. If you define a host as an :ref:`alias<invent…
3713 msgid "you must use the alias in your pattern. In the example above, you must use ``host1`` in your…
3717 msgid "Advanced pattern options"
3721 msgid "The common patterns described above will meet most of your needs, but Ansible offers several…
3725 msgid "Using variables in patterns"
3729 msgid "You can use variables to enable passing group specifiers via the ``-e`` argument to ansible-…
3733 msgid "Using group position in patterns"
3737 msgid "You can define a host or subset of hosts by its position in a group. For example, given the …
3741 msgid "you can use subscripts to select individual hosts or ranges within the webservers group::"
3745 msgid "Using regexes in patterns"
3749 msgid "You can specify a pattern as a regular expression by starting the pattern with ``~``::"
3753 msgid "Patterns and ansible-playbook flags"
3757 msgid "You can change the behavior of the patterns defined in playbooks using command-line options.…
3761 msgid "Finally, you can use ``--limit`` to read the list of hosts from a file by prefixing the file…
3765 msgid "If :ref:`RETRY_FILES_ENABLED` is set to ``True``, a ``.retry`` file will be created after th…
3769 msgid "ansible-playbook site.yml --limit @site.retry"
3773 msgid "To apply your knowledge of patterns with Ansible commands and playbooks, read :ref:`intro_ad…
3777 msgid "Learning the Ansible configuration management language"
3781 msgid "Windows Support"
3785 msgid "This page has been split up and moved to the new section :ref:`windows`."
3789 msgid "Working With Modules"
3793 msgid "Ansible ships with a number of modules (called the 'module library') that can be executed di…
3797 msgid "Users can also write their own modules. These modules can control system resources, like ser…
3803 msgid "Examples of using modules in /usr/bin/ansible"
3821 msgid ":ref:`playbooks_intro`"
3825 msgid "Introduction to using modules with /usr/bin/ansible-playbook"
3829 msgid ":ref:`developing_modules_general`"
3834 msgid "How to write your own modules"
3839 msgid ":ref:`developing_api`"
3844 msgid "Examples of using modules with the Python API"
3848 msgid ":ref:`interpreter_discovery`"
3852 msgid "Configuring the right Python interpreter on target hosts"
3856 msgid "Introduction to modules"
3860 msgid "Modules (also referred to as \"task plugins\" or \"library plugins\") are discrete units of …
3864 msgid "You can execute modules from the command line::"
3868 msgid "Each module supports taking arguments.  Nearly all modules take ``key=value`` arguments, spa…
3872 msgid "From playbooks, Ansible modules are executed in a very similar way::"
3876 msgid "Another way to pass arguments to a module is using YAML syntax, also called 'complex args' :…
3880 msgid "All modules return JSON format data. This means modules can be written in any programming la…
3884 msgid "You can access the documentation for each module from the command line with the ansible-doc …
3888 msgid "For a list of all available modules, see the :ref:`Collection docs <list_of_collections>`, o…
3893 msgid "Examples of using modules with /usr/bin/ansible-playbook"
3897 msgid "Module Maintenance & Support"
3901 msgid "If you are using a module and you discover a bug, you may want to know where to report that …
3905 msgid "Starting in Ansible 2.10, most modules live in collections. The distribution method for each…
3909 msgid "Maintenance"
3913 msgid "Collection"
3917 msgid "Code location"
3921 msgid "Maintained by"
3925 msgid "ansible.builtin"
3929 msgid "`ansible/ansible repo`_ on GitHub"
3933 msgid "core team"
3937 msgid "distributed on Galaxy"
3942 msgid "various; follow ``repo`` link"
3946 msgid "community or partners"
3950 msgid "distributed on Automation Hub"
3954 msgid "content team or partners"
3958 msgid "Issue Reporting"
3962 msgid "If you find a bug that affects a plugin in the main Ansible repo, also known as ``ansible-co…
3966 msgid "Confirm that you are running the latest stable version of Ansible or the devel branch."
3970 msgid "Look at the `issue tracker in the Ansible repo <https://github.com/ansible/ansible/issues>`_…
3975 msgid "Create an issue if one does not already exist. Include as much detail as you can about the b…
3979 msgid "If you find a bug that affects a plugin in a Galaxy collection:"
3983 msgid "Find the collection on Galaxy."
3987 msgid "Find the issue tracker for the collection."
3991 msgid "Look there to see if an issue has already been filed."
3995 msgid "Some partner collections may be hosted in private repositories."
3999 msgid "If you are not sure whether the behavior you see is a bug, if you have questions, if you wan…
4003 msgid "If you find a bug that affects a module in an Automation Hub collection:"
4007 msgid "If the collection offers an Issue Tracker link on Automation Hub, click there and open an is…
4011 msgid "Support"
4015 msgid "All plugins that remain in ``ansible-core`` and all collections hosted in Automation Hub are…
4019 msgid "Search paths in Ansible"
4023 msgid "You can control the paths Ansible searches to find resources on your control node (including…
4027 msgid "Config paths"
4031 msgid "By default these should be relative to the config file, some are specifically relative to th…
4035 msgid "Task paths"
4039 msgid "Task paths include two different scopes: task evaluation and task execution. For task evalua…
4043 msgid "The magic of 'local' paths"
4047 msgid "Lookups and action plugins both use a special 'search magic' to find things, taking the curr…
4051 msgid "Using this magic, relative paths get attempted first with a 'files|templates|vars' appended …
4055 msgid "By default, Ansible does not search the current working directory unless it happens to coinc…
4059 msgid "As for includes, they try the path of the included file first and fall back to the play/role…
4063 msgid "Working with playbooks"
4067 msgid "Playbooks record and execute Ansible's configuration, deployment, and orchestration function…
4071 msgid "If Ansible modules are the tools in your workshop, playbooks are your instruction manuals, a…
4075 msgid "At a basic level, playbooks can be used to manage configurations of and deployments to remot…
4079 msgid "Playbooks are designed to be human-readable and are developed in a basic text language.  The…
4083 msgid "You should look at `Example Playbooks <https://github.com/ansible/ansible-examples>`_ while …
4087 msgid "Advanced Syntax"
4091 msgid "The advanced YAML syntax examples on this page give you more control over the data placed in…
4095 msgid "Unsafe or raw strings"
4100 msgid "When handling values returned by lookup plugins, Ansible uses a data type called ``unsafe`` …
4104 msgid "You can use the same ``unsafe`` data type in variables you define, to prevent templating err…
4108 msgid "In a playbook::"
4112 msgid "For complex variables such as hashes or arrays, use ``!unsafe`` on the individual elements::"
4116 msgid "YAML anchors and aliases: sharing variable values"
4120 msgid "`YAML anchors and aliases <https://yaml.org/spec/1.2/spec.html#id2765878>`_ help you define,…
4124 msgid "Here, ``app1`` and ``app2`` share the values for ``opts`` and ``port`` using the anchor ``&j…
4128 msgid "Anchors and aliases also let you share complex sets of variable values, including nested var…
4132 msgid "This is inefficient and, at scale, means more maintenance. To incorporate the version value …
4136 msgid "Now, you can re-use the value of ``app_version`` within the value of  ``custom_name`` and us…
4140 msgid "You've anchored the value of ``version`` with the ``&my_version`` anchor, and re-used it wit…
4152 msgid "All about variables"
4156 msgid ":doc:`complex_data_manipulation`"
4160 msgid "Doing complex data manipulation in Ansible"
4169 msgid "`User Mailing List <https://groups.google.com/group/ansible-project>`_"
4195 msgid "Have a question?  Stop by the google group!"
4199 msgid "Asynchronous actions and polling"
4203 msgid "By default Ansible runs tasks synchronously, holding the connection to the remote node open …
4207 msgid "Asynchronous ad hoc tasks"
4211 msgid "You can execute long-running operations in the background with :ref:`ad hoc tasks <intro_adh…
4215 msgid "To check on the job status later, use the ``async_status`` module, passing it the job ID tha…
4219 msgid "Ansible can also check on the status of your long-running job automatically with polling. In…
4223 msgid "Poll mode is smart so all jobs will be started before polling begins on any machine. Be sure…
4227 msgid "Asynchronous mode is best suited to long-running shell commands or software upgrades. Runnin…
4231 msgid "Asynchronous playbook tasks"
4235 msgid ":ref:`Playbooks <working_with_playbooks>` also support asynchronous mode and polling, with a…
4239 msgid "Avoid connection timeouts: poll > 0"
4243 msgid "If you want to set a longer timeout limit for a certain task in your playbook, use ``async``…
4247 msgid "To avoid timeouts on a task, specify its maximum runtime and how frequently you would like t…
4251 msgid "The default poll value is set by the :ref:`DEFAULT_POLL_INTERVAL` setting. There is no defau…
4255 msgid "As of Ansible 2.3, async does not support check mode and will fail the task when run in chec…
4259 msgid "When an async task completes with polling enabled, the temporary async job cache file (by de…
4263 msgid "Run tasks concurrently: poll = 0"
4267 msgid "If you want to run multiple tasks in a playbook concurrently, use ``async`` with ``poll`` se…
4271 msgid "To run a playbook task asynchronously::"
4275 msgid "Do not specify a poll value of 0 with operations that require exclusive locks (such as yum t…
4279 msgid "Using a higher value for ``--forks`` will result in kicking off asynchronous tasks even fast…
4283 msgid "When running with ``poll: 0``, Ansible will not automatically cleanup the async job cache fi…
4287 msgid "If you need a synchronization point with an async task, you can register it to obtain its jo…
4291 msgid "If the value of ``async:`` is not high enough, this will cause the \"check on it later\" tas…
4295 msgid "To run multiple asynchronous tasks while limiting the number of tasks running concurrently::"
4300 msgid ":ref:`playbooks_strategies`"
4304 msgid "Options for controlling playbook execution"
4324 msgid "`User Mailing List <https://groups.google.com/group/ansible-devel>`_"
4328 msgid "Tips and tricks"
4332 msgid "These tips and tricks have helped us optimize our Ansible usage, and we offer them here as s…
4336 msgid "General tips"
4340 msgid "These concepts apply to all Ansible activities and artifacts."
4344 msgid "Keep it simple"
4348 msgid "Whenever you can, do things simply. Use advanced features only when necessary, and select th…
4352 msgid "Use version control"
4356 msgid "Keep your playbooks, roles, inventory, and variables files in git or another version control…
4360 msgid "Playbook tips"
4364 msgid "These tips help make playbooks and roles easier to read, maintain, and debug."
4368 msgid "Use whitespace"
4372 msgid "Generous use of whitespace, for example, a blank line before each block or task, makes a pla…
4376 msgid "Always name tasks"
4380 msgid "Task names are optional, but extremely useful. In its output, Ansible shows you the name of …
4384 msgid "Always mention the state"
4388 msgid "For many modules, the 'state' parameter is optional. Different modules have different defaul…
4392 msgid "Use comments"
4396 msgid "Even with task names and explicit state, sometimes a part of a playbook or role (or inventor…
4400 msgid "Inventory tips"
4404 msgid "These tips help keep your inventory well organized."
4408 msgid "Use dynamic inventory with clouds"
4412 msgid "With cloud providers and other systems that maintain canonical lists of your infrastructure,…
4416 msgid "Group inventory by function"
4420 msgid "A system can be in multiple groups.  See :ref:`intro_inventory` and :ref:`intro_patterns`. I…
4424 msgid "Separate production and staging inventory"
4428 msgid "You can keep your production environment separate from development, test, and staging enviro…
4432 msgid "Keep vaulted variables safely visible"
4436 msgid "You should encrypt sensitive or secret variables with Ansible Vault. However, encrypting the…
4440 msgid "Create a ``group_vars/`` subdirectory named after the group."
4444 msgid "Inside this subdirectory, create two files named ``vars`` and ``vault``."
4448 msgid "In the ``vars`` file, define all of the variables needed, including any sensitive ones."
4452 msgid "Copy all of the sensitive variables over to the ``vault`` file and prefix these variables wi…
4456 msgid "Adjust the variables in the ``vars`` file to point to the matching ``vault_`` variables usin…
4460 msgid "Encrypt the ``vault`` file to protect its contents."
4464 msgid "Use the variable name from the ``vars`` file in your playbooks."
4468 msgid "When running a playbook, Ansible finds the variables in the unencrypted file, which pulls th…
4472 msgid "Execution tricks"
4476 msgid "These tips apply to using Ansible, rather than to Ansible artifacts."
4480 msgid "Try it in staging first"
4484 msgid "Testing changes in a staging environment before rolling them out in production is always a g…
4488 msgid "Update in batches"
4492 msgid "Use the 'serial' keyword to control how many machines you update at once in the batch. See :…
4496 msgid "Handling OS and distro differences"
4500 msgid "Group variables files and the ``group_by`` module work together to help Ansible execute acro…
4504 msgid "The first play categorizes all systems into dynamic groups based on the operating system nam…
4508 msgid "In this example, CentOS machines get the value of '42' for asdf, but other machines get '10'…
4512 msgid "You can use the same setup with ``include_vars`` when you only need OS-specific variables, n…
4516 msgid "This pulls in variables from the group_vars/os_CentOS.yml file."
4524 msgid ":ref:`yaml_syntax`"
4532 msgid "Learn about YAML syntax"
4537 msgid "Review the basic playbook features"
4543 msgid "Learn how to extend Ansible by writing your own modules"
4549 msgid ":ref:`intro_patterns`"
4555 msgid "Learn about how to select hosts"
4561 msgid "`GitHub examples directory <https://github.com/ansible/ansible-examples>`_"
4566 msgid "Complete playbook files from the github project source"
4570 msgid "Blocks"
4574 msgid "Blocks create logical groups of tasks. Blocks also offer ways to handle task errors, similar…
4578 msgid "Grouping tasks with blocks"
4582 msgid "All tasks in a block inherit directives applied at the block level. Most of what you can app…
4586 msgid "Block example with named tasks inside the block"
4590 msgid "In the example above, the 'when' condition will be evaluated before Ansible runs each of the…
4594 msgid "Names for blocks have been available since Ansible 2.3. We recommend using names in all task…
4598 msgid "Handling errors with blocks"
4602 msgid "You can control how Ansible responds to task errors using blocks with ``rescue`` and ``alway…
4606 msgid "Rescue blocks specify tasks to run when an earlier task in a block fails. This approach is s…
4610 msgid "Block error handling example"
4614 msgid "You can also add an ``always`` section to a block. Tasks in the ``always`` section run no ma…
4618 msgid "Block with always section"
4622 msgid "Together, these elements offer complex error handling."
4626 msgid "Block with all sections"
4630 msgid "The tasks in the ``block`` execute normally. If any tasks in the block return ``failed``, th…
4634 msgid "If an error occurs in the block and the rescue task succeeds, Ansible reverts the failed sta…
4638 msgid "You can use blocks with ``flush_handlers`` in a rescue task to ensure that all handlers run …
4642 msgid "Block run handlers in error handling"
4646 msgid "Ansible provides a couple of variables for tasks in the ``rescue`` portion of a block:"
4650 msgid "ansible_failed_task"
4654 msgid "The task that returned 'failed' and triggered the rescue. For example, to get the name use `…
4658 msgid "ansible_failed_result"
4662 msgid "The captured return result of the failed task that triggered the rescue. This would equate t…
4675 msgid "Playbook organization by roles"
4679 msgid "Validating tasks: check mode and diff mode"
4683 msgid "Ansible provides two modes of execution that validate tasks: check mode and diff mode. These…
4687 msgid "Using check mode"
4691 msgid "Check mode is just a simulation. It will not generate output for tasks that use :ref:`condit…
4695 msgid "Enforcing or preventing check mode on tasks"
4699 msgid "If you want certain tasks to run in check mode always, or never, regardless of whether you r…
4703 msgid "To force a task to run in check mode, even when the playbook is called without ``--check``, …
4707 msgid "To force a task to run in normal mode and make changes to the system, even when the playbook…
4711 msgid "Running single tasks with ``check_mode: yes`` can be useful for testing Ansible modules, eit…
4715 msgid "Prior to version 2.2 only the equivalent of ``check_mode: no`` existed. The notation for tha…
4719 msgid "Skipping tasks or ignoring errors in check mode"
4723 msgid "If you want to skip a task or ignore errors on a task when you run Ansible in check mode, yo…
4727 msgid "Using diff mode"
4731 msgid "The ``--diff`` option for ansible-playbook can be used alone or with ``--check``. When you r…
4735 msgid "Diff mode produces a large amount of output, so it is best used when checking a single host …
4739 msgid "Enforcing or preventing diff mode on tasks"
4743 msgid "Because the ``--diff`` option can reveal sensitive information, you can disable it for a tas…
4747 msgid "Conditionals"
4751 msgid "In a playbook, you may want to execute different tasks, or have different goals, depending o…
4755 msgid "Ansible uses Jinja2 :ref:`tests <playbooks_tests>` and :ref:`filters <playbooks_filters>` in…
4759 msgid "There are many options to control execution flow in Ansible. You can find more examples of s…
4763 msgid "Basic conditionals with ``when``"
4767 msgid "The simplest conditional statement applies to a single task. Create the task, then add a ``w…
4771 msgid "Conditionals based on ansible_facts"
4775 msgid "Often you want to execute or skip a task based on facts. Facts are attributes of individual …
4779 msgid "You can install a certain package only when the operating system is a particular version."
4783 msgid "You can skip configuring a firewall on hosts with internal IP addresses."
4787 msgid "You can perform cleanup tasks only when a filesystem is getting full."
4791 msgid "See :ref:`commonly_used_facts` for a list of facts that frequently appear in conditional sta…
4795 msgid "Here is a sample conditional based on a fact:"
4799 msgid "If you have multiple conditions, you can group them with parentheses:"
4803 msgid "You can use `logical operators <https://jinja.palletsprojects.com/en/master/templates/#logic…
4807 msgid "If a fact or variable is a string, and you need to run a mathematical comparison on it, use …
4811 msgid "Conditions based on registered variables"
4815 msgid "Often in a playbook you want to execute or skip a task based on the outcome of an earlier ta…
4819 msgid "Register the outcome of the earlier task as a variable."
4823 msgid "Create a conditional test based on the registered variable."
4827 msgid "You create the name of the registered variable using the ``register`` keyword. A registered …
4831 msgid "You can use registered results in the loop of a task if the variable is a list. If the varia…
4835 msgid "The string content of a registered variable can be empty. If you want to run another task on…
4839 msgid "Ansible always registers something in a registered variable for every host, even on hosts wh…
4843 msgid "Older versions of Ansible used ``success`` and ``fail``, but ``succeeded`` and ``failed`` us…
4847 msgid "Conditionals based on variables"
4851 msgid "You can also create conditionals based on variables defined in the playbooks or inventory. B…
4855 msgid "With the variables above, Ansible would run one of these tasks and skip the other:"
4859 msgid "If a required variable has not been set, you can skip or fail using Jinja2's `defined` test.…
4863 msgid "This is especially useful in combination with the conditional import of vars files (see belo…
4867 msgid "Using conditionals in loops"
4871 msgid "If you combine a ``when`` statement with a :ref:`loop <playbooks_loops>`, Ansible processes …
4875 msgid "If you need to skip the whole task when the loop variable is undefined, use the `|default` f…
4879 msgid "You can do the same thing when looping over a dict:"
4883 msgid "Loading custom facts"
4887 msgid "You can provide your own facts, as described in :ref:`developing_modules`.  To run them, jus…
4891 msgid "Conditionals with re-use"
4895 msgid "You can use conditionals with re-usable tasks files, playbooks, or roles. Ansible executes t…
4899 msgid "Conditionals with imports"
4903 msgid "When you add a conditional to an import statement, Ansible applies the condition to all task…
4908 msgid "Ansible expands this at execution time to the equivalent of::"
4912 msgid "Thus if ``x`` is initially undefined, the ``debug`` task will be skipped. If this is not the…
4916 msgid "You can apply conditions to ``import_playbook`` as well as to the other ``import_*`` stateme…
4920 msgid "Conditionals with includes"
4924 msgid "When you use a conditional on an ``include_*`` statement, the condition is applied only to t…
4928 msgid "By using ``include_tasks`` instead of ``import_tasks``, both tasks from ``other_tasks.yml`` …
4932 msgid "Conditionals with roles"
4936 msgid "There are three ways to apply conditions to roles:"
4940 msgid "Add the same condition or conditions to all tasks in the role by placing your ``when`` state…
4944 msgid "Add the same condition or conditions to all tasks in the role by placing your ``when`` state…
4948 msgid "Add a condition or conditions to individual tasks or blocks within the role itself. This is …
4952 msgid "When you incorporate a role in your playbook statically with the ``roles`` keyword, Ansible …
4956 msgid "Selecting variables, files, or templates based on facts"
4960 msgid "Sometimes the facts about a host determine the values you want to use for certain variables …
4964 msgid "name your vars files, templates, or files to match the Ansible fact that differentiates them"
4968 msgid "select the correct vars file, template, or file for each host with a variable based on that …
4972 msgid "Ansible separates variables from tasks, keeping your playbooks from turning into arbitrary c…
4976 msgid "Selecting variables files based on facts"
4980 msgid "You can create a playbook that works on multiple platforms and OS versions with a minimum of…
4984 msgid "Then import those variables files based on the facts you gather on the hosts in your playboo…
4988 msgid "Ansible gathers facts on the hosts in the webservers group, then interpolates the variable \…
4992 msgid "Selecting files and templates based on facts"
4996 msgid "You can use the same approach when different OS flavors or versions require different config…
5000 msgid "For example, you can template out a configuration file that is very different between, say, …
5004 msgid "Commonly-used facts"
5008 msgid "The following Ansible facts are frequently used in conditionals."
5012 msgid "ansible_facts['distribution']"
5017 msgid "Possible values (sample, not complete list)::"
5021 msgid "ansible_facts['distribution_major_version']"
5025 msgid "The major version of the operating system. For example, the value is `16` for Ubuntu 16.04."
5029 msgid "ansible_facts['os_family']"
5049 msgid ":ref:`playbooks_best_practices`"
5068 msgid "Tips and tricks for playbooks"
5072 msgid "Debugging tasks"
5076 msgid "Ansible offers a task debugger so you can fix errors during execution instead of editing you…
5080 msgid "Enabling the debugger"
5084 msgid "The debugger is not enabled by default. If you want to invoke the debugger during playbook e…
5088 msgid "Use one of these three methods to enable the debugger:"
5092 msgid "with the debugger keyword"
5096 msgid "in configuration or an environment variable, or"
5100 msgid "as a strategy"
5104 msgid "Enabling the debugger with the ``debugger`` keyword"
5108 msgid "You can use the ``debugger`` keyword to enable (or disable) the debugger for a specific play…
5112 msgid "Value"
5116 msgid "Result"
5120 msgid "always"
5124 msgid "Always invoke the debugger, regardless of the outcome"
5128 msgid "never"
5132 msgid "Never invoke the debugger, regardless of the outcome"
5136 msgid "on_failed"
5140 msgid "Only invoke the debugger if a task fails"
5144 msgid "on_unreachable"
5148 msgid "Only invoke the debugger if a host is unreachable"
5152 msgid "on_skipped"
5156 msgid "Only invoke the debugger if the task is skipped"
5160 msgid "When you use the ``debugger`` keyword, the value you specify overrides any global configurat…
5164 msgid "Examples of using the ``debugger`` keyword"
5168 msgid "Example of setting the ``debugger`` keyword on a task:"
5172 msgid "Example of setting the ``debugger`` keyword on a play:"
5176 msgid "Example of setting the ``debugger`` keyword at multiple levels:"
5180 msgid "In this example, the debugger is set to ``never`` at the play level and to ``on_failed`` at …
5184 msgid "Enabling the debugger in configuration or an environment variable"
5188 msgid "You can enable the task debugger globally with a setting in ansible.cfg or with an environme…
5192 msgid "To enable the task debugger from ansible.cfg, add this setting to the defaults section::"
5196 msgid "To enable the task debugger with an environment variable, pass the variable when you run you…
5200 msgid "When you enable the debugger globally, every failed task invokes the debugger, unless the ro…
5204 msgid "Enabling the debugger as a strategy"
5208 msgid "If you are running legacy playbooks or roles, you may see the debugger enabled as a :ref:`st…
5212 msgid "Or in ansible.cfg::"
5216 msgid "This backwards-compatible method, which matches Ansible versions before 2.5, may be removed …
5220 msgid "Resolving errors in the debugger"
5224 msgid "After Ansible invokes the debugger, you can use the seven :ref:`debugger commands <available…
5228 msgid "If you run this playbook, Ansible invokes the debugger when the task fails. From the debug p…
5232 msgid "Changing the task arguments in the debugger to use ``var1`` instead of ``wrong_var`` makes t…
5236 msgid "Available debug commands"
5240 msgid "You can use these seven commands at the debug prompt:"
5244 msgid "Command"
5248 msgid "Shortcut"
5252 msgid "Action"
5256 msgid "print"
5260 msgid "p"
5264 msgid "Print information about the task"
5268 msgid "task.args[*key*] = *value*"
5273 msgid "no shortcut"
5277 msgid "Update module arguments"
5281 msgid "task_vars[*key*] = *value*"
5285 msgid "Update task variables (you must ``update_task`` next)"
5289 msgid "update_task"
5293 msgid "u"
5297 msgid "Recreate a task with updated task variables"
5301 msgid "redo"
5305 msgid "r"
5309 msgid "Run the task again"
5313 msgid "continue"
5317 msgid "c"
5321 msgid "Continue executing, starting with the next task"
5325 msgid "quit"
5329 msgid "q"
5333 msgid "Quit the debugger"
5337 msgid "For more details, see the individual descriptions and examples below."
5341 msgid "Print command"
5345 msgid "``print *task/task.args/task_vars/host/result*`` prints information about the task::"
5349 msgid "Update args command"
5353 msgid "``task.args[*key*] = *value*`` updates a module argument. This sample playbook has an invali…
5357 msgid "When you run the playbook, the invalid package name triggers an error, and Ansible invokes t…
5361 msgid "After you update the module argument, use ``redo`` to run the task again with the new args."
5365 msgid "Update vars command"
5369 msgid "``task_vars[*key*] = *value*`` updates the ``task_vars``. You could fix the playbook above b…
5373 msgid "After you update the task variables, you must use ``update_task`` to load the new variables …
5377 msgid "In 2.5 this was updated from ``vars`` to ``task_vars`` to avoid conflicts with the ``vars()`…
5381 msgid "Update task command"
5385 msgid "``u`` or ``update_task`` recreates the task from the original task data structure and templa…
5389 msgid "Redo command"
5393 msgid "``r`` or ``redo`` runs the task again."
5397 msgid "Continue command"
5401 msgid "``c`` or ``continue`` continues executing, starting with the next task."
5405 msgid "Quit command"
5409 msgid "``q`` or ``quit`` quits the debugger. The playbook execution is aborted."
5413 msgid "How the debugger interacts with the free strategy"
5417 msgid "With the default ``linear`` strategy enabled, Ansible halts execution while the debugger is …
5421 msgid ":ref:`playbooks_start_and_step`"
5425 msgid "Running playbooks while debugging or testing"
5429 msgid "Controlling where tasks run: delegation and local actions"
5433 msgid "By default Ansible gathers facts and executes all tasks on the machines that match the ``hos…
5437 msgid "Tasks that cannot be delegated"
5441 msgid "Some tasks always execute on the controller. These tasks, including ``include``, ``add_host`…
5445 msgid "Delegating tasks"
5449 msgid "If you want to perform a task on one host with reference to other hosts, use the ``delegate_…
5453 msgid "The first and third tasks in this play run on 127.0.0.1, which is the machine running Ansibl…
5457 msgid "You can use a local action to call 'rsync' to recursively copy files to the managed servers:…
5461 msgid "Note that you must have passphrase-less SSH keys or an ssh-agent configured for this to work…
5465 msgid "To specify more arguments, use the following syntax::"
5469 msgid "The `ansible_host` variable reflects the host a task is delegated to."
5473 msgid "Delegating facts"
5477 msgid "Delegating Ansible tasks is like delegating tasks in the real world - your groceries belong …
5481 msgid "This task gathers facts for the machines in the dbservers group and assigns the facts to tho…
5485 msgid "Local playbooks"
5489 msgid "It may be useful to use a playbook locally on a remote host, rather than by connecting over …
5493 msgid "To run an entire playbook locally, just set the ``hosts:`` line to ``hosts: 127.0.0.1`` and …
5497 msgid "Alternatively, a local connection can be used in a single playbook play, even if other plays…
5501 msgid "If you set the connection to local and there is no ansible_python_interpreter set, modules w…
5505 msgid "More ways to control how and where Ansible executes"
5509 msgid "`Ansible Examples on GitHub <https://github.com/ansible/ansible-examples>`_"
5513 msgid "Many examples of full-stack deployments"
5517 msgid "Setting the remote environment"
5521 msgid "You can use the ``environment`` keyword at the play, block, or task level to set an environm…
5525 msgid "When you set a value with ``environment:`` at the play or block level, it is available only …
5529 msgid "Setting the remote environment in a task"
5533 msgid "You can set the environment directly at the task level::"
5537 msgid "You can re-use environment settings by defining them as variables in your play and accessing…
5541 msgid "You can store environment settings for re-use in multiple playbooks by defining them in a gr…
5545 msgid "You can set the remote environment at the play level::"
5549 msgid "These examples show proxy settings, but you can provide any number of settings this way."
5553 msgid "Working with language-specific version managers"
5557 msgid "Some language-specific version managers (such as rbenv and nvm) require you to set environme…
5561 msgid "The example above uses ``ansible_env`` as part of the PATH. Basing variables on ``ansible_en…
5565 msgid "Environment variables are normally passed in clear text (shell plugin dependent) so they are…
5569 msgid "You can also specify the environment at the task level::"
5573 msgid "Error handling in playbooks"
5577 msgid "When Ansible receives a non-zero return code from a command or a failure from a module, by d…
5581 msgid "Ignoring failed commands"
5585 msgid "By default Ansible stops executing tasks on a host when a task fails on that host. You can u…
5589 msgid "The ``ignore_errors`` directive only works when the task is able to run and returns a value …
5593 msgid "Ignoring unreachable host errors"
5597 msgid "You can ignore a task failure due to the host instance being 'UNREACHABLE' with the ``ignore…
5601 msgid "And at the playbook level::"
5605 msgid "Resetting unreachable hosts"
5609 msgid "If Ansible cannot connect to a host, it marks that host as 'UNREACHABLE' and removes it from…
5613 msgid "Handlers and failure"
5617 msgid "Ansible runs :ref:`handlers <handlers>` at the end of each play. If a task notifies a handle…
5621 msgid "You can change this behavior with the ``--force-handlers`` command-line option, by including…
5625 msgid "Defining failure"
5629 msgid "Ansible lets you define what \"failure\" means in each task using the ``failed_when`` condit…
5633 msgid "You may check for failure by searching for a word or phrase in the output of a command::"
5637 msgid "or based on the return code::"
5641 msgid "You can also combine multiple conditions for failure. This task will fail if both conditions…
5645 msgid "If you want the task to fail when only one condition is satisfied, change the ``failed_when`…
5649 msgid "If you have too many conditions to fit neatly into one line, you can split it into a multi-l…
5653 msgid "Defining \"changed\""
5657 msgid "Ansible lets you define when a particular task has \"changed\" a remote node using the ``cha…
5661 msgid "You can also combine multiple conditions to override \"changed\" result::"
5665 msgid "See :ref:`controlling_what_defines_failure` for more conditional syntax examples."
5669 msgid "Ensuring success for command and shell"
5673 msgid "The :ref:`command <command_module>` and :ref:`shell <shell_module>` modules care about retur…
5677 msgid "Aborting a play on all hosts"
5681 msgid "Sometimes you want a failure on a single host, or failures on a certain percentage of hosts,…
5685 msgid "Aborting on the first error: any_errors_fatal"
5689 msgid "If you set ``any_errors_fatal`` and a task returns an error, Ansible finishes the fatal task…
5694 msgid "You can use this feature when all tasks must be 100% successful to continue playbook executi…
5698 msgid "In this example Ansible starts the software upgrade on the front ends only if all of the loa…
5702 msgid "Setting a maximum failure percentage"
5706 msgid "By default, Ansible continues to execute tasks as long as there are hosts that have not yet …
5710 msgid "The ``max_fail_percentage`` setting applies to each batch when you use it with :ref:`serial …
5714 msgid "The percentage set must be exceeded, not equaled. For example, if serial were set to 4 and y…
5718 msgid "Controlling errors in blocks"
5722 msgid "You can also use blocks to define responses to task errors. This approach is similar to exce…
5737 msgid ":ref:`playbooks_conditionals`"
5749 msgid "Conditional statements in playbooks"
5753 msgid "Using filters to manipulate data"
5757 msgid "Filters let you transform JSON data into YAML data, split a URL to extract the hostname, get…
5761 msgid "Because templating happens on the Ansible controller, **not** on the target host, filters ex…
5765 msgid "Handling undefined variables"
5769 msgid "Filters can help you manage missing or undefined variables by providing defaults or making s…
5773 msgid "Providing default values"
5777 msgid "You can provide default values for variables directly in your templates using the Jinja2 'de…
5781 msgid "In the above example, if the variable 'some_variable' is not defined, Ansible uses the defau…
5785 msgid "Beginning in version 2.8, attempting to access an attribute of an Undefined value in Jinja w…
5789 msgid "If you want to use the default value when variables evaluate to false or an empty string you…
5793 msgid "Making variables optional"
5797 msgid "By default Ansible requires values for all variables in a templated expression. However, you…
5801 msgid "In this example, the default mode for the files ``/tmp/foo`` and ``/tmp/bar`` is determined …
5805 msgid "If you are \"chaining\" additional filters after the ``default(omit)`` filter, you should in…
5809 msgid "Defining mandatory values"
5813 msgid "If you configure Ansible to ignore undefined variables, you may want to define some values a…
5817 msgid "The variable value will be used as is, but the template evaluation will raise an error if it…
5821 msgid "Defining different values for true/false/null (ternary)"
5825 msgid "You can create a test, then define one value to use when the test returns true and another w…
5829 msgid "In addition, you can define a one value to use on true, one value on false and a third value…
5833 msgid "Managing data types"
5837 msgid "You might need to know, change, or set the data type on a variable. For example, a registere…
5841 msgid "Discovering the data type"
5845 msgid "If you are unsure of the underlying Python type of a variable, you can use the ``type_debug`…
5849 msgid "Transforming dictionaries into lists"
5853 msgid "Use the ``dict2items`` filter to transform a dictionary into a list of items suitable for :r…
5858 msgid "Dictionary data (before applying the ``dict2items`` filter)::"
5863 msgid "List data (after applying the ``dict2items`` filter)::"
5867 msgid "The ``dict2items`` filter is the reverse of the ``items2dict`` filter."
5871 msgid "If you want to configure the names of the keys, the ``dict2items`` filter accepts 2 keyword …
5875 msgid "Transforming lists into dictionaries"
5879 msgid "Use the ``items2dict`` filter to transform a list into a dictionary, mapping the content int…
5883 msgid "List data (before applying the ``items2dict`` filter)::"
5887 msgid "Dictionary data (after applying the ``items2dict`` filter)::"
5891 msgid "The ``items2dict`` filter is the reverse of the ``dict2items`` filter."
5895 msgid "Not all lists use ``key`` to designate keys and ``value`` to designate values. For example::"
5899 msgid "In this example, you must pass the ``key_name`` and ``value_name`` arguments to configure th…
5903 msgid "If you do not pass these arguments, or do not pass the correct values for your list, you wil…
5907 msgid "Forcing the data type"
5911 msgid "You can cast values as certain types. For example, if you expect the input \"True\" from a :…
5915 msgid "If you want to perform a mathematical comparison on a fact and you want Ansible to recognize…
5919 msgid "Formatting data: YAML and JSON"
5923 msgid "You can switch a data structure in a template from or to JSON or YAML format, with options f…
5927 msgid "For human readable output, you can use::"
5931 msgid "You can change the indentation of either format::"
5935 msgid "The ``to_yaml`` and ``to_nice_yaml`` filters use the `PyYAML library`_ which has a default 8…
5939 msgid "The filter does support passing through other YAML parameters. For a full list, see the `PyY…
5943 msgid "If you are reading in some already formatted data::"
5948 msgid "for example::"
5952 msgid "Filter `to_json` and Unicode support"
5956 msgid "By default `to_json` and `to_nice_json` will convert data received to ASCII, so::"
5960 msgid "will return::"
5964 msgid "To keep Unicode characters, pass the parameter `ensure_ascii=False` to the filter::"
5968 msgid "To parse multi-document YAML strings, the ``from_yaml_all`` filter is provided. The ``from_y…
5972 msgid "Combining and selecting data"
5976 msgid "You can combine data from multiple sources and types, and select values from large data stru…
5980 msgid "Combining items from multiple lists: zip and zip_longest"
5984 msgid "To get a list combining the elements of other lists use ``zip``::"
5988 msgid "To always exhaust all lists use ``zip_longest``::"
5992 msgid "Similarly to the output of the ``items2dict`` filter mentioned above, these filters can be u…
5996 msgid "List data (before applying the ``zip`` filter)::"
6000 msgid "Dictionary data (after applying the ``zip`` filter)::"
6004 msgid "Combining objects and subelements"
6008 msgid "The ``subelements`` filter produces a product of an object and the subelement values of that…
6012 msgid "Data before applying the ``subelements`` filter::"
6016 msgid "Data after applying the ``subelements`` filter::"
6020 msgid "You can use the transformed data with ``loop`` to iterate over the same subelement for multi…
6024 msgid "Combining hashes/dictionaries"
6028 msgid "The ``combine`` filter allows hashes to be merged. For example, the following would override…
6032 msgid "The resulting hash would be::"
6036 msgid "The filter can also take multiple arguments to merge::"
6040 msgid "In this case, keys in ``d`` would override those in ``c``, which would override those in ``b…
6044 msgid "The filter also accepts two optional parameters: ``recursive`` and ``list_merge``."
6048 msgid "recursive"
6052 msgid "Is a boolean, default to ``False``. Should the ``combine`` recursively merge nested hashes. …
6056 msgid "list_merge"
6060 msgid "Is a string, its possible values are ``replace`` (default), ``keep``, ``append``, ``prepend`…
6064 msgid "If ``recursive=False`` (the default), nested hash aren't merged::"
6079 msgid "This would result in::"
6083 msgid "If ``recursive=True``, recurse into nested hash and merge their keys::"
6087 msgid "If ``list_merge='replace'`` (the default), arrays from the right hash will \"replace\" the o…
6091 msgid "If ``list_merge='keep'``, arrays from the left hash will be kept::"
6095 msgid "If ``list_merge='append'``, arrays from the right hash will be appended to the ones in the l…
6099 msgid "If ``list_merge='prepend'``, arrays from the right hash will be prepended to the ones in the…
6103 msgid "If ``list_merge='append_rp'``, arrays from the right hash will be appended to the ones in th…
6107 msgid "If ``list_merge='prepend_rp'``, the behavior is similar to the one for ``append_rp``, but el…
6111 msgid "``recursive`` and ``list_merge`` can be used together::"
6115 msgid "Selecting values from arrays or hashtables"
6119 msgid "The `extract` filter is used to map from a list of indices to a list of values from a contai…
6123 msgid "The results of the above expressions would be::"
6127 msgid "The filter can take another argument::"
6131 msgid "This takes the list of hosts in group 'x', looks them up in `hostvars`, and then looks up th…
6135 msgid "The third argument to the filter can also be a list, for a recursive lookup inside the conta…
6139 msgid "This would return a list containing the value of `b['a']['x']['y']`."
6143 msgid "Combining lists"
6147 msgid "This set of filters returns a list of combined lists."
6151 msgid "permutations"
6155 msgid "To get permutations of a list::"
6159 msgid "combinations"
6163 msgid "Combinations always require a set size::"
6167 msgid "Also see the :ref:`zip_filter`"
6171 msgid "products"
6175 msgid "The product filter returns the `cartesian product <https://docs.python.org/3/library/itertoo…
6179 msgid "Selecting JSON data: JSON queries"
6183 msgid "To select a single element or a data subset from a complex data structure in JSON format (fo…
6188 msgid "This filter has migrated to the `community.general <https://galaxy.ansible.com/community/gen…
6192 msgid "You must manually install the **jmespath** dependency on the Ansible controller before using…
6196 msgid "Consider this data structure::"
6200 msgid "To extract all clusters from this structure, you can use the following query::"
6204 msgid "To extract all server names::"
6208 msgid "To extract ports from cluster1::"
6212 msgid "You can use a variable to make the query more readable."
6216 msgid "To print out the ports from cluster1 in a comma separated string::"
6220 msgid "In the example above, quoting literals using backticks avoids escaping quotes and maintains …
6224 msgid "You can use YAML `single quote escaping <https://yaml.org/spec/current.html#id2534365>`_::"
6228 msgid "Escaping single quotes within single quotes in YAML is done by doubling the single quote."
6232 msgid "To get a hash map with all ports and names of a cluster::"
6236 msgid "To extract ports from all clusters with name starting with 'server1'::"
6240 msgid "To extract ports from all clusters with name containing 'server1'::"
6244 msgid "while using ``starts_with`` and ``contains``, you have to use `` to_json | from_json `` filt…
6248 msgid "Randomizing data"
6252 msgid "When you need a randomly generated value, use one of these filters."
6256 msgid "Random MAC addresses"
6260 msgid "This filter can be used to generate a random MAC address from a string prefix."
6264 msgid "To get a random MAC address from a string prefix starting with '52:54:00'::"
6268 msgid "Note that if anything is wrong with the prefix string, the filter will issue an error."
6272 msgid "As of Ansible version 2.9, you can also initialize the random number generator from a seed t…
6276 msgid "Random items or numbers"
6280 msgid "The ``random`` filter in Ansible is an extension of the default Jinja2 random filter, and ca…
6284 msgid "To get a random item from a list::"
6288 msgid "To get a random number between 0 (inclusive) and a specified integer (exclusive)::"
6292 msgid "To get a random number from 0 to 100 but in steps of 10::"
6296 msgid "To get a random number from 1 to 100 but in steps of 10::"
6300 msgid "You can initialize the random number generator from a seed to create random-but-idempotent n…
6306 msgid "If you use the ``seed`` parameter, you will get a different result with Python 3 and Python …
6310 msgid "Shuffling a list"
6314 msgid "The ``shuffle`` filter randomizes an existing list, giving a different order every invocatio…
6318 msgid "To get a random list from an existing  list::"
6322 msgid "You can initialize the shuffle generator from a seed to generate a random-but-idempotent ord…
6326 msgid "The shuffle filter returns a list whenever possible. If you use it with a non 'listable' ite…
6330 msgid "Managing list variables"
6334 msgid "You can search for the minimum or maximum value in a list, or flatten a multi-level list."
6338 msgid "To get the minimum value from list of numbers::"
6342 msgid "To get the minimum value in a list of objects::"
6346 msgid "To get the maximum value from a list of numbers::"
6350 msgid "To get the maximum value in a list of objects::"
6354 msgid "Flatten a list (same thing the `flatten` lookup does)::"
6358 msgid "Flatten only the first level of a list (akin to the `items` lookup)::"
6362 msgid "Preserve nulls in a list, by default flatten removes them. ::"
6366 msgid "Selecting from sets or lists (set theory)"
6370 msgid "You can select or combine items from sets or lists."
6374 msgid "To get a unique set from a list::"
6378 msgid "To get a union of two lists::"
6382 msgid "To get the intersection of 2 lists (unique list of all items in both)::"
6386 msgid "To get the difference of 2 lists (items in 1 that don't exist in 2)::"
6390 msgid "To get the symmetric difference of 2 lists (items exclusive to each list)::"
6394 msgid "Calculating numbers (math)"
6398 msgid "You can calculate logs, powers, and roots of numbers with Ansible filters. Jinja2 provides o…
6402 msgid "Get the logarithm (default is e)::"
6406 msgid "Get the base 10 logarithm::"
6410 msgid "Give me the power of 2! (or 5)::"
6414 msgid "Square root, or the 5th::"
6418 msgid "Managing network interactions"
6422 msgid "These filters help you with common network tasks."
6426 msgid "These filters have migrated to the `ansible.netcommon <https://galaxy.ansible.com/ansible/ne…
6430 msgid "IP address filters"
6434 msgid "To test if a string is a valid IP address::"
6438 msgid "You can also require a specific IP protocol version::"
6442 msgid "IP address filter can also be used to extract specific information from an IP address. For e…
6446 msgid "More information about ``ipaddr`` filter and complete usage guide can be found in :ref:`play…
6450 msgid "Network CLI filters"
6454 msgid "To convert the output of a network device CLI command into structured JSON output, use the `…
6458 msgid "The ``parse_cli`` filter will load the spec file and pass the command output through it, ret…
6462 msgid "The spec file should be valid formatted YAML.  It defines how to parse the CLI output and re…
6467 msgid "The spec file above will return a JSON data structure that is a list of hashes with the pars…
6471 msgid "The same command could be parsed into a hash by using the key and values directives.  Here i…
6475 msgid "Another common use case for parsing CLI commands is to break a large command into blocks tha…
6479 msgid "The example above will parse the output of ``show interface`` into a list of hashes."
6483 msgid "The network filters also support parsing the output of a CLI command using the TextFSM libra…
6487 msgid "Use of the TextFSM filter requires the TextFSM library to be installed."
6491 msgid "Network XML filters"
6495 msgid "To convert the XML output of a network device command into structured JSON output, use the `…
6499 msgid "The ``parse_xml`` filter will load the spec file and pass the command output through formatt…
6503 msgid "The spec file should be valid formatted YAML. It defines how to parse the XML output and ret…
6507 msgid "Below is an example of a valid spec file that will parse the output from the ``show vlan | d…
6511 msgid "The same command could be parsed into a hash by using the key and values directives.  Here i…
6515 msgid "The value of ``top`` is the XPath relative to the XML root node. In the example XML output g…
6519 msgid "``items`` is a dictionary of key-value pairs that map user-defined names to XPath expression…
6523 msgid "Attributes of XML tags can be extracted using XPath expressions. The value of ``state`` in t…
6527 msgid "For more information on supported XPath expressions, see `XPath Support <https://docs.python…
6531 msgid "Network VLAN filters"
6535 msgid "Use the ``vlan_parser`` filter to transform an unsorted list of VLAN integers into a sorted …
6539 msgid "Vlans are listed in ascending order."
6543 msgid "Three or more consecutive VLANs are listed with a dash."
6547 msgid "The first line of the list can be first_line_len characters long."
6551 msgid "Subsequent list lines can be other_line_len characters."
6555 msgid "To sort a VLAN list::"
6559 msgid "This example renders the following sorted list::"
6563 msgid "Another example Jinja template::"
6567 msgid "This allows for dynamic generation of VLAN lists on a Cisco IOS tagged interface. You can st…
6571 msgid "Encrypting and checksumming strings and passwords"
6575 msgid "To get the sha1 hash of a string::"
6579 msgid "To get the md5 hash of a string::"
6583 msgid "Get a string checksum::"
6587 msgid "Other hashes (platform dependent)::"
6591 msgid "To get a sha512 password hash (random salt)::"
6595 msgid "To get a sha256 password hash with a specific salt::"
6599 msgid "An idempotent method to generate unique hashes per system is to use a salt that is consisten…
6603 msgid "Hash types available depend on the control system running Ansible, 'hash' depends on `hashli…
6607 msgid "Some hash types allow providing a rounds parameter::"
6611 msgid "Manipulating text"
6615 msgid "Several filters work with text, including URLs, file names, and path names."
6619 msgid "Adding comments to files"
6623 msgid "The ``comment`` filter lets you create comments in a file from text in a template, with a va…
6627 msgid "produces this output:"
6631 msgid "Ansible offers styles for comments in C (``//...``), C block (``/*...*/``), Erlang (``%...``…
6635 msgid "You can define a custom comment character. This filter::"
6639 msgid "produces:"
6643 msgid "You can fully customize the comment style::"
6647 msgid "That creates the following output:"
6651 msgid "The filter can also be applied to any Ansible variable. For example to make the output of th…
6655 msgid "and then use the variable with the `comment` filter::"
6659 msgid "which produces this output:"
6663 msgid "URLEncode Variables"
6667 msgid "The ``urlencode`` filter quotes data for use in a URL path or query using UTF-8::"
6671 msgid "Splitting URLs"
6675 msgid "The ``urlsplit`` filter extracts the fragment, hostname, netloc, password, path, port, query…
6679 msgid "Searching strings with regular expressions"
6683 msgid "To search in a string or extract parts of a string with a regular expression, use the ``rege…
6687 msgid "To extract all occurrences of regex matches in a string, use the ``regex_findall`` filter::"
6691 msgid "To replace text in a string with regex, use the ``regex_replace`` filter::"
6695 msgid "If you want to match the whole string and you are using ``*`` make sure to always wraparound…
6699 msgid "Prior to ansible 2.0, if ``regex_replace`` filter was used with variables inside YAML argume…
6703 msgid "To escape special characters within a standard Python regex, use the ``regex_escape`` filter…
6707 msgid "To escape special characters within a POSIX basic regex, use the ``regex_escape`` filter wit…
6711 msgid "Managing file names and path names"
6715 msgid "To get the last name of a file path, like 'foo.txt' out of '/etc/asdf/foo.txt'::"
6719 msgid "To get the last name of a windows style file path (new in version 2.0)::"
6723 msgid "To separate the windows drive letter from the rest of a file path (new in version 2.0)::"
6727 msgid "To get only the windows drive letter::"
6731 msgid "To get the rest of the path without the drive letter::"
6735 msgid "To get the directory from a path::"
6739 msgid "To get the directory from a windows path (new version 2.0)::"
6743 msgid "To expand a path containing a tilde (`~`) character (new in version 1.5)::"
6747 msgid "To expand a path containing environment variables::"
6751 msgid "`expandvars` expands local variables; using it on remote paths can lead to errors."
6755 msgid "To get the real path of a link (new in version 1.8)::"
6759 msgid "To get the relative path of a link, from a start point (new in version 1.7)::"
6763 msgid "To get the root and extension of a path or file name (new in version 2.0)::"
6767 msgid "The ``splitext`` filter always returns a pair of strings. The individual components can be a…
6771 msgid "To join one or more path components::"
6775 msgid "Manipulating strings"
6779 msgid "To add quotes for shell usage::"
6783 msgid "To concatenate a list into a string::"
6787 msgid "To split a sting into a list::"
6791 msgid "To work with Base64 encoded strings::"
6795 msgid "As of version 2.6, you can define the type of encoding to use, the default is ``utf-8``::"
6799 msgid "The ``string`` filter is only required for Python 2 and ensures that text to encode is a uni…
6803 msgid "Managing UUIDs"
6807 msgid "To create a namespaced UUIDv5::"
6811 msgid "To create a namespaced UUIDv5 using the default Ansible namespace '361E6D51-FAEC-444A-9079-3…
6815 msgid "To make use of one attribute from each item in a list of complex variables, use the :func:`J…
6819 msgid "Handling dates and times"
6823 msgid "To get a date object from a string use the `to_datetime` filter::"
6827 msgid "For a full list of format codes for working with python date format strings, see https://doc…
6831 msgid "To format a date using a string (like with the shell date command), use the \"strftime\" fil…
6835 msgid "To get all string possibilities, check https://docs.python.org/3/library/time.html#time.strf…
6839 msgid "Getting Kubernetes resource names"
6843 msgid "These filters have migrated to the `kuberernetes.core <https://galaxy.ansible.com/kubernetes…
6847 msgid "Use the \"k8s_config_resource_name\" filter to obtain the name of a Kubernetes ConfigMap or …
6851 msgid "This can then be used to reference hashes in Pod specifications::"
6861 msgid ":ref:`about_playbooks`"
6873 msgid ":ref:`playbooks_loops`"
6882 msgid "Looping in playbooks"
6886 msgid "ipaddr filter"
6890 msgid "``ipaddr()`` is a Jinja2 filter designed to provide an interface to the `netaddr`_ Python pa…
6894 msgid "The ``ipaddr()`` filter migrated to the `ansible.netcommon <https://galaxy.ansible.com/ansib…
6898 msgid "To use this filter in Ansible, you need to install the `netaddr`_ Python library on a comput…
6906 msgid "Topics"
6910 msgid "Basic tests"
6914 msgid "``ipaddr()`` is designed to return the input value if a query is True, and ``False`` if a qu…
6918 msgid "You can also pass the values as variables::"
6922 msgid "Here are some example test results of various input strings::"
6926 msgid "Sometimes you need either IPv4 or IPv6 addresses. To filter only for a particular type, ``ip…
6930 msgid "Example use of an IPv4 filter::"
6934 msgid "A similar example of an IPv6 filter::"
6938 msgid "Here's some example test results to look for IPv4 addresses::"
6942 msgid "And the same data filtered for IPv6 addresses::"
6946 msgid "Filtering lists"
6950 msgid "You can filter entire lists - ``ipaddr()`` will return a list with values valid for a partic…
6954 msgid "Wrapping IPv6 addresses in [ ] brackets"
6958 msgid "Some configuration files require IPv6 addresses to be \"wrapped\" in square brackets (``[ ]`…
6962 msgid "As you can see, ``ipwrap()`` did not filter out non-IP address values, which is usually what…
6966 msgid "Basic queries"
6970 msgid "You can provide a single argument to each ``ipaddr()`` filter. The filter will then treat it…
6974 msgid "Types of queries include:"
6978 msgid "query by name: ``ansible.netcommon.ipaddr('address')``, ``ansible.netcommon.ipv4('network')`…
6982 msgid "query by CIDR range: ``ansible.netcommon.ipaddr('192.168.0.0/24')``, ``ansible.netcommon.ipv…
6986 msgid "query by index number: ``ansible.netcommon.ipaddr('1')``, ``ansible.netcommon.ipaddr('-1')``…
6990 msgid "If a query type is not recognized, Ansible will raise an error."
6994 msgid "Getting information about hosts and networks"
6999 msgid "Here's our test list again::"
7003 msgid "Let's take the list above and get only those elements that are host IP addresses and not net…
7007 msgid "As you can see, even though some values had a host address with a CIDR prefix, they were dro…
7011 msgid "Filtering by IP address type also works::"
7015 msgid "You can check if IP addresses or network ranges are accessible on a public Internet, or if t…
7019 msgid "You can check which values are specifically network ranges::"
7023 msgid "You can also check how many IP addresses can be in a certain range::"
7027 msgid "By specifying a network range as a query, you can check if a given value is in that range::"
7031 msgid "If you specify a positive or negative integer as a query, ``ipaddr()`` will treat this as an…
7035 msgid "You can also select IP addresses from a range by their index, from the start or end of the r…
7039 msgid "Getting information from host/prefix values"
7043 msgid "You frequently use a combination of IP addresses and subnet prefixes (\"CIDR\"), this is eve…
7047 msgid "Here's an example set of two host prefixes (with some \"control\" values)::"
7051 msgid "First, let's make sure that we only work with correct host/prefix values, not just subnets o…
7055 msgid "In Debian-based systems, the network configuration stored in the ``/etc/network/interfaces``…
7059 msgid "In the above example, we needed to handle the fact that values were stored in a list, which …
7063 msgid "If needed, you can extract subnet and prefix information from the 'host/prefix' value:"
7067 msgid "Converting subnet masks to CIDR notation"
7071 msgid "Given a subnet in the form of network address and subnet mask, the ``ipaddr()`` filter can c…
7075 msgid "First concatenate the network and netmask::"
7079 msgid "This result can be converted to canonical form with ``ipaddr()`` to produce a subnet in CIDR…
7083 msgid "Getting information about the network in CIDR notation"
7087 msgid "Given an IP address, the ``ipaddr()`` filter can produce the network address in CIDR notatio…
7091 msgid "Here's an example of IP address::"
7095 msgid "This can be used to obtain the network address in CIDR notation format::"
7099 msgid "IP address conversion"
7103 msgid "You can convert IPv4 addresses into IPv6 addresses::"
7107 msgid "Converting from IPv6 to IPv4 works very rarely::"
7111 msgid "But we can make a double conversion if needed::"
7115 msgid "You can convert IP addresses to integers, the same way that you can convert integers into IP…
7119 msgid "You can convert IPv4 address to `Hexadecimal notation <https://en.wikipedia.org/wiki/Hexadec…
7123 msgid "You can convert IP addresses to PTR records::"
7127 msgid "Converting IPv4 address to a 6to4 address"
7131 msgid "A `6to4`_ tunnel is a way to access the IPv6 Internet from an IPv4-only network. If you have…
7135 msgid "To convert your IPv4 address, just send it through the ``'6to4'`` filter. It will be automat…
7139 msgid "Finding IP addresses within a range"
7143 msgid "To find usable IP addresses within an IP range, try these ``ipaddr`` filters:"
7147 msgid "To find the next usable IP address in a range, use ``next_usable`` ::"
7151 msgid "To find the last usable IP address from a range, use ``last_usable``::"
7155 msgid "To find the available range of IP addresses from the given network address, use ``range_usab…
7159 msgid "To find the peer IP address for a point to point link, use ``peer``::"
7163 msgid "To return the nth ip from a network, use the filter ``nthhost``::"
7167 msgid "``nthhost`` also supports a negative value::"
7171 msgid "To find the next nth usable IP address in relation to another within a range, use ``next_nth…
7175 msgid "If there is no usable address, it returns an empty string::"
7179 msgid "Just like ``next_nth_ansible``, you have ``previous_nth_usable`` to find the previous usable…
7183 msgid "Testing if a address belong to a network range"
7187 msgid "The ``network_in_usable`` filter returns whether an address passed as an argument is usable …
7191 msgid "The ``network_in_network`` filter returns whether an address or a network passed as argument…
7195 msgid "To check whether multiple addresses belong to a network, use the ``reduce_on_network`` filte…
7199 msgid "IP Math"
7203 msgid "The ``ipmath()`` filter can be used to do simple IP math/arithmetic."
7207 msgid "Here are a few simple examples::"
7211 msgid "Subnet manipulation"
7215 msgid "The ``ipsubnet()`` filter can be used to manipulate network subnets in several ways."
7219 msgid "Here is an example IP address and subnet::"
7223 msgid "To check if a given string is a subnet, pass it through the filter without any arguments. If…
7227 msgid "If you specify a subnet size as the first parameter of the  ``ipsubnet()`` filter, and the s…
7231 msgid "The second argument of the ``ipsubnet()`` filter is an index number; by specifying it you ca…
7235 msgid "If you specify an IP address instead of a subnet, and give a subnet size as the first argume…
7239 msgid "By specifying an index number as a second argument, you can select smaller and smaller subne…
7243 msgid "By specifying another subnet as a second argument, if the second subnet includes the first, …
7247 msgid "If the second subnet doesn't include the first subnet, the ``ipsubnet()`` filter raises an e…
7251 msgid "You can use the ``ipsubnet()`` filter with the ``ipaddr()`` filter to, for example, split a …
7255 msgid "Because of the size of IPv6 subnets, iteration over all of them to find the correct one may …
7259 msgid "Subnet Merging"
7263 msgid "The ``cidr_merge()`` filter can be used to merge subnets or individual addresses into their …
7267 msgid "Changing the action from 'merge' to 'span' will instead return the smallest subnet which con…
7271 msgid "MAC address filter"
7275 msgid "You can use the ``hwaddr()`` filter to check if a given string is a MAC address or convert i…
7279 msgid "The supported formats result in the following conversions for the ``1a:2b:3c:4d:5e:6f`` MAC …
7283 msgid "Generate an IPv6 address in Stateless Configuration (SLAAC)"
7287 msgid "the filter ``slaac()`` generates an IPv6 address for a given network and a MAC Address in St…
7291 msgid "`ansible.netcommon <https://galaxy.ansible.com/ansible/netcommon>`_"
7295 msgid "Ansible network collection for common code"
7300 msgid ":ref:`playbooks_filters`"
7304 msgid "Introduction to Jinja2 filters and their uses"
7308 msgid "Handlers: running operations on change"
7312 msgid "Sometimes you want a task to run only when a change is made on a machine. For example, you m…
7316 msgid "Handler example"
7320 msgid "This playbook, ``verify-apache.yml``, contains a single play with a handler::"
7324 msgid "In this example playbook, the second task notifies the handler. A single task can notify mor…
7328 msgid "Controlling when handlers run"
7332 msgid "By default, handlers run after all the tasks in a particular play have been completed. This …
7336 msgid "If you need handlers to run before the end of the play, add a task to flush them using the :…
7340 msgid "The ``meta: flush_handlers`` task triggers any handlers that have been notified at that poin…
7344 msgid "Using variables with handlers"
7348 msgid "You may want your Ansible handlers to use variables. For example, if the name of a service v…
7352 msgid "If the variable used in the handler name is not available, the entire play fails. Changing t…
7356 msgid "Instead, place variables in the task parameters of your handler. You can load the values usi…
7360 msgid "Handlers can also \"listen\" to generic topics, and tasks can notify those topics as follows…
7364 msgid "This use makes it much easier to trigger multiple handlers. It also decouples handlers from …
7368 msgid "Handlers always run in the order they are defined, not in the order listed in the notify-sta…
7372 msgid "Handler names and `listen` topics live in a global namespace."
7376 msgid "Handler names are templatable and `listen` topics are not."
7380 msgid "Use unique handler names. If you trigger more than one handler with the same name, the first…
7384 msgid "You can notify a handler defined inside a static include."
7388 msgid "You cannot notify a handler defined inside a dynamic include."
7392 msgid "A handler can not run import_role or include_role."
7396 msgid "When using handlers within roles, note that:"
7400 msgid "handlers notified within ``pre_tasks``, ``tasks``, and ``post_tasks`` sections are automatic…
7404 msgid "handlers notified within ``roles`` section are automatically flushed at the end of ``tasks``…
7408 msgid "handlers are play scoped and as such can be used outside of the role they are defined in."
7412 msgid "Intro to playbooks"
7416 msgid "Ansible Playbooks offer a repeatable, re-usable, simple configuration management and multi-m…
7420 msgid "Playbooks can:"
7424 msgid "declare configurations"
7428 msgid "orchestrate steps of any manual ordered process, on multiple sets of machines, in a defined …
7432 msgid "launch tasks synchronously or :ref:`asynchronously <playbooks_async>`"
7436 msgid "Playbook syntax"
7440 msgid "Playbooks are expressed in YAML format with a minimum of syntax. If you are not familiar wit…
7444 msgid "A playbook is composed of one or more 'plays' in an ordered list. The terms 'playbook' and '…
7448 msgid "Playbook execution"
7452 msgid "A playbook runs in order from top to bottom. Within each play, tasks also run in order from …
7456 msgid "the managed nodes to target, using a :ref:`pattern <intro_patterns>`"
7460 msgid "at least one task to execute"
7464 msgid "In Ansible 2.10 and later, we recommend you use the fully-qualified collection name in your …
7468 msgid "In this example, the first play targets the web servers; the second play targets the databas…
7472 msgid "Your playbook can include more than just a hosts line and tasks. For example, the playbook a…
7476 msgid "Task execution"
7480 msgid "By default, Ansible executes each task in order, one at a time, against all machines matched…
7484 msgid "When you run a playbook, Ansible returns information about connections, the ``name`` lines o…
7488 msgid "Desired state and 'idempotency'"
7492 msgid "Most Ansible modules check whether the desired final state has already been achieved, and ex…
7496 msgid "Running playbooks"
7500 msgid "To run your playbook, use the :ref:`ansible-playbook` command::"
7504 msgid "Use the ``--verbose`` flag when running your playbook to see detailed output from successful…
7508 msgid "Ansible-Pull"
7512 msgid "Should you want to invert the architecture of Ansible, so that nodes check in to a central l…
7516 msgid "The ``ansible-pull`` is a small script that will checkout a repo of configuration instructio…
7520 msgid "Assuming you load balance your checkout location, ``ansible-pull`` scales essentially infini…
7524 msgid "Run ``ansible-pull --help`` for details."
7528 msgid "There's also a `clever playbook <https://github.com/ansible/ansible-examples/blob/master/lan…
7532 msgid "Verifying playbooks"
7536 msgid "You may want to verify your playbooks to catch syntax errors and other problems before you r…
7540 msgid "ansible-lint"
7544 msgid "You can use `ansible-lint <https://docs.ansible.com/ansible-lint/index.html>`_ for detailed,…
7548 msgid "The `ansible-lint default rules <https://docs.ansible.com/ansible-lint/rules/default_rules.h…
7552 msgid "`ansible-lint <https://docs.ansible.com/ansible-lint/index.html>`_"
7556 msgid "Learn how to test Ansible Playbooks syntax"
7560 msgid "Tips for managing playbooks in the real world"
7564 msgid "Learn to extend Ansible by writing your own modules"
7568 msgid "Complete end-to-end playbook examples"
7572 msgid "Lookups"
7576 msgid "Lookup plugins retrieve data from outside sources such as files, databases, key/value stores…
7580 msgid "Using lookups in variables"
7584 msgid "You can populate variables using lookups. Ansible evaluates the value each time it is execut…
7588 msgid "For more details and a list of lookup plugins in ansible-core, see :ref:`plugins_lookup`. Yo…
7592 msgid "Loops"
7596 msgid "Ansible offers the ``loop``, ``with_<lookup>``, and ``until`` keywords to execute a task mul…
7600 msgid "We added ``loop`` in Ansible 2.5. It is not yet a full replacement for ``with_<lookup>``, bu…
7604 msgid "We have not deprecated the use of ``with_<lookup>`` - that syntax will still be valid for th…
7608 msgid "We are looking to improve ``loop`` syntax - watch this page and the `changelog <https://gith…
7612 msgid "Comparing ``loop`` and ``with_*``"
7616 msgid "The ``with_<lookup>`` keywords rely on :ref:`lookup_plugins` - even  ``items`` is a lookup."
7620 msgid "The ``loop`` keyword is equivalent to ``with_list``, and is the best choice for simple loops…
7624 msgid "The ``loop`` keyword will not accept a string as input, see :ref:`query_vs_lookup`."
7628 msgid "Generally speaking, any use of ``with_*`` covered in :ref:`migrating_to_loop` can be updated…
7632 msgid "Be careful when changing ``with_items`` to ``loop``, as ``with_items`` performed implicit si…
7636 msgid "you would need::"
7640 msgid "Any ``with_*`` statement that requires using ``lookup`` within a loop should not be converte…
7644 msgid "it's cleaner to keep::"
7648 msgid "Standard loops"
7652 msgid "Iterating over a simple list"
7656 msgid "Repeated tasks can be written as standard loops over a simple list of strings. You can defin…
7660 msgid "You can define the list in a variables file, or in the 'vars' section of your play, then ref…
7664 msgid "Either of these examples would be the equivalent of::"
7668 msgid "You can pass a list directly to a parameter for some plugins. Most of the packaging modules,…
7672 msgid "Check the :ref:`module documentation <modules_by_category>` to see if you can pass a list to…
7676 msgid "Iterating over a list of hashes"
7680 msgid "If you have a list of hashes, you can reference subkeys in a loop. For example::"
7684 msgid "When combining :ref:`conditionals <playbooks_conditionals>` with a loop, the ``when:`` state…
7688 msgid "Iterating over a dictionary"
7692 msgid "To loop over a dict, use the  :ref:`dict2items <dict_filter>`:"
7696 msgid "Here, we are iterating over `tag_data` and printing the key and the value from it."
7700 msgid "Registering variables with a loop"
7704 msgid "You can register the output of a loop as a variable. For example::"
7708 msgid "When you use ``register`` with a loop, the data structure placed in the variable will contai…
7712 msgid "Subsequent loops over the registered variable to inspect the results may look like::"
7716 msgid "During iteration, the result of the current item will be placed in the variable::"
7720 msgid "Complex loops"
7724 msgid "Iterating over nested lists"
7728 msgid "You can use Jinja2 expressions to iterate over complex lists. For example, a loop can combin…
7732 msgid "Retrying a task until a condition is met"
7736 msgid "You can use the ``until`` keyword to retry a task until a certain condition is met.  Here's …
7740 msgid "This task runs up to 5 times with a delay of 10 seconds between each attempt. If the result …
7744 msgid "To see the results of individual retries, run the play with ``-vv``."
7748 msgid "When you run a task with ``until`` and register the result as a variable, the registered var…
7752 msgid "You must set the ``until`` parameter if you want a task to retry. If ``until`` is not define…
7756 msgid "Looping over inventory"
7760 msgid "To loop over your inventory, or just a subset of it, you can use a regular ``loop`` with the…
7764 msgid "There is also a specific lookup plugin ``inventory_hostnames`` that can be used like this::"
7768 msgid "More information on the patterns can be found in :ref:`intro_patterns`."
7772 msgid "Ensuring list input for ``loop``: using ``query`` rather than ``lookup``"
7776 msgid "The ``loop`` keyword requires a list as input, but the ``lookup`` keyword returns a string o…
7780 msgid "You can force ``lookup`` to return a list to ``loop`` by using ``wantlist=True``, or you can…
7784 msgid "These examples do the same thing::"
7788 msgid "Adding controls to loops"
7792 msgid "The ``loop_control`` keyword lets you manage your loops in useful ways."
7796 msgid "Limiting loop output with ``label``"
7800 msgid "When looping over complex data structures, the console output of your task can be enormous. …
7804 msgid "The output of this task will display just the ``name`` field for each ``item`` instead of th…
7808 msgid "This is for making console output more readable, not protecting sensitive data. If there is …
7812 msgid "Pausing within a loop"
7816 msgid "To control the time (in seconds) between the execution of each item in a task loop, use the …
7820 msgid "Tracking progress through a loop with ``index_var``"
7824 msgid "To keep track of where you are in a loop, use the ``index_var`` directive with ``loop_contro…
7828 msgid "`index_var` is 0 indexed."
7832 msgid "Defining inner and outer variable names with ``loop_var``"
7836 msgid "You can nest two looping tasks using ``include_tasks``. However, by default Ansible sets the…
7840 msgid "If Ansible detects that the current loop is using a variable which has already been defined,…
7844 msgid "Extended loop variables"
7848 msgid "As of Ansible 2.8 you can get extended loop information using the ``extended`` option to loo…
7852 msgid "Variable"
7856 msgid "``ansible_loop.allitems``"
7860 msgid "The list of all items in the loop"
7864 msgid "``ansible_loop.index``"
7868 msgid "The current iteration of the loop. (1 indexed)"
7872 msgid "``ansible_loop.index0``"
7876 msgid "The current iteration of the loop. (0 indexed)"
7880 msgid "``ansible_loop.revindex``"
7884 msgid "The number of iterations from the end of the loop (1 indexed)"
7888 msgid "``ansible_loop.revindex0``"
7892 msgid "The number of iterations from the end of the loop (0 indexed)"
7896 msgid "``ansible_loop.first``"
7900 msgid "``True`` if first iteration"
7904 msgid "``ansible_loop.last``"
7908 msgid "``True`` if last iteration"
7912 msgid "``ansible_loop.length``"
7916 msgid "The number of items in the loop"
7920 msgid "``ansible_loop.previtem``"
7924 msgid "The item from the previous iteration of the loop. Undefined during the first iteration."
7928 msgid "``ansible_loop.nextitem``"
7932 msgid "The item from the following iteration of the loop. Undefined during the last iteration."
7936 msgid "Accessing the name of your loop_var"
7940 msgid "As of Ansible 2.8 you can get the name of the value provided to ``loop_control.loop_var`` us…
7944 msgid "For role authors, writing roles that allow loops, instead of dictating the required ``loop_v…
7948 msgid "Migrating from with_X to loop"
7952 msgid "In most cases, loops work best with the ``loop`` keyword instead of ``with_X`` style loops. …
7956 msgid "These examples show how to convert many common ``with_`` style loops to ``loop`` and filters…
7960 msgid "with_list"
7964 msgid "``with_list`` is directly replaced by ``loop``."
7968 msgid "with_items"
7972 msgid "``with_items`` is replaced by ``loop`` and the ``flatten`` filter."
7976 msgid "with_indexed_items"
7980 msgid "``with_indexed_items`` is replaced by ``loop``, the ``flatten`` filter and ``loop_control.in…
7984 msgid "with_flattened"
7988 msgid "``with_flattened`` is replaced by ``loop`` and the ``flatten`` filter."
7992 msgid "with_together"
7996 msgid "``with_together`` is replaced by ``loop`` and the ``zip`` filter."
8000 msgid "Another example with complex data"
8004 msgid "with_dict"
8008 msgid "``with_dict`` can be substituted by ``loop`` and either the ``dictsort`` or ``dict2items`` f…
8012 msgid "with_sequence"
8016 msgid "``with_sequence`` is replaced by ``loop`` and the ``range`` function, and potentially the ``…
8020 msgid "with_subelements"
8024 msgid "``with_subelements`` is replaced by ``loop`` and the ``subelements`` filter."
8028 msgid "with_nested/with_cartesian"
8032 msgid "``with_nested`` and ``with_cartesian`` are replaced by loop and the ``product`` filter."
8036 msgid "with_random_choice"
8040 msgid "``with_random_choice`` is replaced by just use of the ``random`` filter, without need of ``l…
8044 msgid "Module defaults"
8048 msgid "If you frequently call the same module with the same arguments, it can be useful to define d…
8052 msgid "Here is a basic example::"
8056 msgid "The ``module_defaults`` keyword can be used at the play, block, and task level. Any module a…
8060 msgid "You can remove any previously established defaults for a module by specifying an empty dict:…
8064 msgid "Any module defaults set at the play level (and block/task level when using ``include_role`` …
8068 msgid "Here are some more realistic use cases for this feature."
8072 msgid "Interacting with an API that requires auth::"
8076 msgid "Setting a default AWS region for specific EC2-related modules::"
8080 msgid "Module defaults groups"
8084 msgid "Ansible 2.7 adds a preview-status feature to group together modules that share common sets o…
8088 msgid "Group"
8092 msgid "Purpose"
8096 msgid "Ansible Version"
8100 msgid "aws"
8104 msgid "Amazon Web Services"
8110 msgid "2.7"
8114 msgid "azure"
8118 msgid "Azure"
8122 msgid "gcp"
8126 msgid "Google Cloud Platform"
8130 msgid "k8s"
8134 msgid "Kubernetes"
8139 msgid "2.8"
8143 msgid "os"
8147 msgid "OpenStack"
8151 msgid "acme"
8155 msgid "ACME"
8162 msgid "2.10"
8166 msgid "docker*"
8170 msgid "Docker"
8174 msgid "ovirt"
8178 msgid "oVirt"
8182 msgid "vmware"
8186 msgid "VMware"
8190 msgid "The `docker_stack <docker_stack_module>`_ module is not included in the ``docker`` defaults …
8194 msgid "Use the groups with ``module_defaults`` by prefixing the group name with ``group/`` - for ex…
8198 msgid "In a playbook, you can set module defaults for whole groups of modules, such as setting a co…
8202 msgid "Interactive input: prompts"
8206 msgid "If you want your playbook to prompt the user for certain input, add a 'vars_prompt' section.…
8210 msgid "Here is a most basic example::"
8214 msgid "The user input is hidden by default but it can be made visible by setting ``private: no``."
8218 msgid "Prompts for individual ``vars_prompt`` variables will be skipped for any variable that is al…
8222 msgid "If you have a variable that changes infrequently, you can provide a default value that can b…
8226 msgid "Encrypting values supplied by ``vars_prompt``"
8230 msgid "You can encrypt the entered value so you can use it, for instance, with the user module to d…
8234 msgid "If you have `Passlib <https://passlib.readthedocs.io/en/stable/>`_ installed, you can use an…
8238 msgid "*des_crypt* - DES Crypt"
8242 msgid "*bsdi_crypt* - BSDi Crypt"
8246 msgid "*bigcrypt* - BigCrypt"
8250 msgid "*crypt16* - Crypt16"
8255 msgid "*md5_crypt* - MD5 Crypt"
8260 msgid "*bcrypt* - BCrypt"
8264 msgid "*sha1_crypt* - SHA-1 Crypt"
8268 msgid "*sun_md5_crypt* - Sun MD5 Crypt"
8273 msgid "*sha256_crypt* - SHA-256 Crypt"
8278 msgid "*sha512_crypt* - SHA-512 Crypt"
8282 msgid "*apr_md5_crypt* - Apache's MD5-Crypt variant"
8286 msgid "*phpass* - PHPass' Portable Hash"
8290 msgid "*pbkdf2_digest* - Generic PBKDF2 Hashes"
8294 msgid "*cta_pbkdf2_sha1* - Cryptacular's PBKDF2 hash"
8298 msgid "*dlitz_pbkdf2_sha1* - Dwayne Litzenberger's PBKDF2 hash"
8302 msgid "*scram* - SCRAM Hash"
8306 msgid "*bsd_nthash* - FreeBSD's MCF-compatible nthash encoding"
8310 msgid "The only parameters accepted are 'salt' or 'salt_size'. You can use your own salt by definin…
8314 msgid "If you do not have Passlib installed, Ansible uses the `crypt <https://docs.python.org/2/lib…
8318 msgid "Allowing special characters in ``vars_prompt`` values"
8322 msgid "Some special characters, such as ``{`` and ``%`` can create templating errors. If you need t…
8326 msgid "Python3 in templates"
8330 msgid "Ansible uses Jinja2 to leverage Python data types and standard functions in templates and va…
8334 msgid "These topics help you design templates that work on both Python2 and Python3. They might als…
8338 msgid "Dictionary views"
8342 msgid "In Python2, the :meth:`dict.keys`, :meth:`dict.values`, and :meth:`dict.items` methods retur…
8346 msgid "In Python3, those methods return a :ref:`dictionary view <python3:dict-views>` object. The s…
8350 msgid "dict.iteritems()"
8354 msgid "Python2 dictionaries have :meth:`~dict.iterkeys`, :meth:`~dict.itervalues`, and :meth:`~dict…
8358 msgid "Python3 dictionaries do not have these methods. Use :meth:`dict.keys`, :meth:`dict.values`, …
8362 msgid "The :ref:`pb-py-compat-dict-views` entry for information on why the :func:`list filter <jinj…
8366 msgid "Re-using Ansible artifacts"
8370 msgid "You can write a simple playbook in one very large file, and most users learn the one-file ap…
8374 msgid "Creating re-usable files and roles"
8378 msgid "Ansible offers four distributed, re-usable artifacts: variables files, task files, playbooks…
8382 msgid "A variables file contains only variables."
8386 msgid "A task file contains only tasks."
8390 msgid "A playbook contains at least one play, and may contain variables, tasks, and other content. …
8394 msgid "A role contains a set of related tasks, variables, defaults, handlers, and even modules or o…
8398 msgid "Re-using playbooks"
8402 msgid "You can incorporate multiple playbooks into a main playbook. However, you can only use impor…
8406 msgid "Importing incorporates playbooks in other playbooks statically. Ansible runs the plays and t…
8410 msgid "Re-using files and roles"
8414 msgid "Ansible offers two ways to re-use files and roles in a playbook: dynamic and static."
8418 msgid "For dynamic re-use, add an ``include_*`` task in the tasks section of a play:"
8422 msgid ":ref:`include_role <include_role_module>`"
8426 msgid ":ref:`include_tasks <include_tasks_module>`"
8430 msgid ":ref:`include_vars <include_vars_module>`"
8434 msgid "For static re-use, add an ``import_*`` task in the tasks section of a play:"
8438 msgid ":ref:`import_role <import_role_module>`"
8442 msgid ":ref:`import_tasks <import_tasks_module>`"
8446 msgid "Task include and import statements can be used at arbitrary depth."
8450 msgid "You can still use the bare :ref:`roles <roles_keyword>` keyword at the play level to incorpo…
8454 msgid "Includes: dynamic re-use"
8458 msgid "Including roles, tasks, or variables adds them to a playbook dynamically. Ansible processes …
8462 msgid "The primary advantage of using ``include_*`` statements is looping. When a loop is used with…
8466 msgid "You can pass variables into includes. See :ref:`ansible_variable_precedence` for more detail…
8470 msgid "Imports: static re-use"
8474 msgid "Importing roles, tasks, or playbooks adds them to a playbook statically. Ansible pre-process…
8478 msgid "You can pass variables to imports. You must pass variables if you want to run an imported fi…
8482 msgid "See :ref:`ansible_variable_precedence` for more details on variable inheritance and preceden…
8486 msgid "Comparing includes and imports: dynamic and static re-use"
8490 msgid "Each approach to re-using distributed Ansible artifacts has advantages and limitations. You …
8494 msgid "Include_*"
8498 msgid "Import_*"
8502 msgid "Type of re-use"
8506 msgid "Dynamic"
8510 msgid "Static"
8514 msgid "When processed"
8518 msgid "At runtime, when encountered"
8522 msgid "Pre-processed during playbook parsing"
8526 msgid "Task or play"
8530 msgid "All includes are tasks"
8534 msgid "``import_playbook`` cannot be a task"
8538 msgid "Task options"
8542 msgid "Apply only to include task itself"
8546 msgid "Apply to all child tasks in import"
8550 msgid "Calling from loops"
8554 msgid "Executed once for each loop item"
8558 msgid "Cannot be used in a loop"
8562 msgid "Using ``--list-tags``"
8566 msgid "Tags within includes not listed"
8570 msgid "All tags appear with ``--list-tags``"
8574 msgid "Using ``--list-tasks``"
8578 msgid "Tasks within includes not listed"
8582 msgid "All tasks appear with ``--list-tasks``"
8586 msgid "Notifying handlers"
8590 msgid "Cannot trigger handlers within includes"
8594 msgid "Can trigger individual imported handlers"
8598 msgid "Using ``--start-at-task``"
8602 msgid "Cannot start at tasks within includes"
8606 msgid "Can start at imported tasks"
8610 msgid "Using inventory variables"
8614 msgid "Can ``include_*: {{ inventory_var }}``"
8618 msgid "Cannot ``import_*: {{ inventory_var }}``"
8622 msgid "With playbooks"
8626 msgid "No ``include_playbook``"
8630 msgid "Can import full playbooks"
8634 msgid "With variables files"
8638 msgid "Can include variables files"
8642 msgid "Use ``vars_files:`` to import variables"
8646 msgid "There are also big differences in resource consumption and performance, imports are quite le…
8650 msgid "Re-using tasks as handlers"
8654 msgid "You can also use includes and imports in the :ref:`handlers` section of a playbook. For inst…
8658 msgid "You can trigger handlers from either an import or an include, but the procedure is different…
8662 msgid "Triggering included (dynamic) handlers"
8666 msgid "Includes are executed at run-time, so the name of the include exists during play execution, …
8670 msgid "Triggering imported (static) handlers"
8674 msgid "Imports are processed before the play begins, so the name of the import no longer exists dur…
8678 msgid ":ref:`utilities_modules`"
8682 msgid "Documentation of the ``include*`` and ``import*`` modules discussed here."
8689 msgid "Review the basic Playbook language features"
8694 msgid "All about variables in playbooks"
8700 msgid "Conditionals in playbooks"
8706 msgid "Loops in playbooks"
8712 msgid ":ref:`ansible_galaxy`"
8717 msgid "How to share roles on galaxy, role management"
8723 msgid "`GitHub Ansible examples <https://github.com/ansible/ansible-examples>`_"
8729 msgid "Complete playbook files from the GitHub project source"
8733 msgid "Including and importing"
8737 msgid "The content on this page has been moved to :ref:`playbooks_reuse`."
8741 msgid "Roles"
8745 msgid "Roles let you automatically load related vars, files, tasks, handlers, and other Ansible art…
8749 msgid "Role directory structure"
8753 msgid "An Ansible role has a defined directory structure with eight main standard directories. You …
8757 msgid "By default Ansible will look in each directory within a role for a ``main.yml`` file for rel…
8761 msgid "``tasks/main.yml`` - the main list of tasks that the role executes."
8765 msgid "``handlers/main.yml`` - handlers, which may be used within or outside this role."
8769 msgid "``library/my_module.py`` - modules, which may be used within this role (see :ref:`embedding_…
8773 msgid "``defaults/main.yml`` - default variables for the role (see :ref:`playbooks_variables` for m…
8777 msgid "``vars/main.yml`` - other variables for the role (see :ref:`playbooks_variables` for more in…
8781 msgid "``files/main.yml`` - files that the role deploys."
8785 msgid "``templates/main.yml`` - templates that the role deploys."
8789 msgid "``meta/main.yml`` - metadata for the role, including role dependencies."
8793 msgid "You can add other YAML files in some directories. For example, you can place platform-specif…
8797 msgid "Roles may also include modules and other plugin types in a directory called ``library``. For…
8801 msgid "Storing and finding roles"
8805 msgid "By default, Ansible looks for roles in two locations:"
8809 msgid "in a directory called ``roles/``, relative to the playbook file"
8813 msgid "in ``/usr/local/etc/ansible/roles``"
8817 msgid "If you store your roles in a different location, set the :ref:`roles_path <DEFAULT_ROLES_PAT…
8821 msgid "Alternatively, you can call a role with a fully qualified path:"
8825 msgid "Using roles"
8829 msgid "You can use roles in three ways:"
8833 msgid "at the play level with the ``roles`` option: This is the classic way of using roles in a pla…
8837 msgid "at the tasks level with ``include_role``: You can reuse roles dynamically anywhere in the ``…
8841 msgid "at the tasks level with ``import_role``: You can reuse roles statically anywhere in the ``ta…
8845 msgid "Using roles at the play level"
8849 msgid "The classic (original) way to use roles is with the ``roles`` option for a given play:"
8853 msgid "When you use the ``roles`` option at the play level, for each role 'x':"
8857 msgid "If roles/x/tasks/main.yml exists, Ansible adds the tasks in that file to the play."
8861 msgid "If roles/x/handlers/main.yml exists, Ansible adds the handlers in that file to the play."
8865 msgid "If roles/x/vars/main.yml exists, Ansible adds the variables in that file to the play."
8869 msgid "If roles/x/defaults/main.yml exists, Ansible adds the variables in that file to the play."
8873 msgid "If roles/x/meta/main.yml exists, Ansible adds any role dependencies in that file to the list…
8877 msgid "Any copy, script, template or include tasks (in the role) can reference files in roles/x/{fi…
8881 msgid "When you use the ``roles`` option at the play level, Ansible treats the roles as static impo…
8885 msgid "Any ``pre_tasks`` defined in the play."
8889 msgid "Any handlers triggered by pre_tasks."
8893 msgid "Each role listed in ``roles:``, in the order listed. Any role dependencies defined in the ro…
8897 msgid "Any ``tasks`` defined in the play."
8901 msgid "Any handlers triggered by the roles or tasks."
8905 msgid "Any ``post_tasks`` defined in the play."
8909 msgid "Any handlers triggered by post_tasks."
8913 msgid "If using tags with tasks in a role, be sure to also tag your pre_tasks, post_tasks, and role…
8917 msgid "You can pass other keywords to the ``roles`` option:"
8921 msgid "When you add a tag to the ``role`` option, Ansible applies the tag to ALL tasks within the r…
8925 msgid "When using ``vars:`` within the ``roles:`` section of a playbook, the variables are added to…
8929 msgid "Including roles: dynamic reuse"
8933 msgid "You can reuse roles dynamically anywhere in the ``tasks`` section of a play using ``include_…
8937 msgid "To include a role:"
8941 msgid "You can pass other keywords, including variables and tags, when including roles:"
8945 msgid "When you add a :ref:`tag <tags>` to an ``include_role`` task, Ansible applies the tag `only`…
8949 msgid "You can conditionally include a role:"
8953 msgid "Importing roles: static reuse"
8957 msgid "You can reuse roles statically anywhere in the ``tasks`` section of a play using ``import_ro…
8961 msgid "You can pass other keywords, including variables and tags, when importing roles:"
8965 msgid "When you add a tag to an ``import_role`` statement, Ansible applies the tag to `all` tasks w…
8969 msgid "Role argument validation"
8973 msgid "Beginning with version 2.11, you may choose to enable role argument validation based on an a…
8977 msgid "Ansible also supports role specifications defined in the role ``meta/main.yml`` file, as wel…
8981 msgid "When role argument validation is used on a role that has defined :ref:`dependencies <role_de…
8985 msgid "Specification format"
8989 msgid "The role argument specification must be defined in a top-level ``argument_specs`` block with…
8993 msgid "entry-point-name"
8997 msgid "The name of the role entry point."
9001 msgid "This should be ``main`` in the case of an unspecified entry point."
9005 msgid "This will be the base name of the tasks file to execute, with no ``.yml`` or ``.yaml`` file …
9009 msgid "short_description"
9013 msgid "A short, one-line description of the entry point."
9017 msgid "The ``short_description`` is displayed by ``ansible-doc -t role -l``."
9021 msgid "description"
9025 msgid "A longer description that may contain multiple lines."
9029 msgid "author"
9033 msgid "Name of the entry point authors."
9037 msgid "Use a multi-line list if there is more than one author."
9041 msgid "options"
9045 msgid "Options are often called \"parameters\" or \"arguments\". This section defines those options…
9049 msgid "For each role option (argument), you may include:"
9053 msgid "option-name"
9057 msgid "The name of the option/argument."
9061 msgid "Detailed explanation of what this option does. It should be written in full sentences."
9065 msgid "type"
9069 msgid "The data type of the option. Default is ``str``."
9073 msgid "If an option is of type ``list``, ``elements`` should be specified."
9077 msgid "required"
9081 msgid "Only needed if ``true``."
9085 msgid "If missing, the option is not required."
9089 msgid "default"
9093 msgid "If ``required`` is false/missing, ``default`` may be specified (assumed 'null' if missing)."
9097 msgid "Ensure that the default value in the docs matches the default value in the code. The actual …
9101 msgid "The default field must not be listed as part of the description, unless it requires addition…
9105 msgid "If the option is a boolean value, you can use any of the boolean values recognized by Ansibl…
9109 msgid "choices"
9113 msgid "List of option values."
9117 msgid "Should be absent if empty."
9121 msgid "elements"
9125 msgid "Specifies the data type for list elements when type is ``list``."
9129 msgid "If this option takes a dict or list of dicts, you can define the structure here."
9133 msgid "Sample specification"
9137 msgid "Running a role multiple times in one playbook"
9141 msgid "Ansible only executes each role once, even if you define it multiple times, unless the param…
9145 msgid "You have two options to force Ansible to run a role more than once."
9149 msgid "Passing different parameters"
9153 msgid "If you pass different parameters in each role definition, Ansible runs the role more than on…
9157 msgid "This playbook runs the ``foo`` role twice:"
9161 msgid "This syntax also runs the ``foo`` role twice;"
9165 msgid "In these examples, Ansible runs ``foo`` twice because each role definition has different par…
9169 msgid "Using ``allow_duplicates: true``"
9173 msgid "Add ``allow_duplicates: true`` to the ``meta/main.yml`` file for the role:"
9177 msgid "In this example, Ansible runs ``foo`` twice because we have explicitly enabled it to do so."
9181 msgid "Using role dependencies"
9185 msgid "Role dependencies let you automatically pull in other roles when using a role. Ansible does …
9189 msgid "Role dependencies are prerequisites, not true dependencies. The roles do not have a parent/c…
9193 msgid "Role dependencies are stored in the ``meta/main.yml`` file within the role directory. This f…
9197 msgid "Ansible always executes roles listed in ``dependencies`` before the role that lists them. An…
9201 msgid "Running role dependencies multiple times in one playbook"
9205 msgid "Ansible treats duplicate role dependencies like duplicate roles listed under ``roles:``: Ans…
9209 msgid "Role deduplication does not consult the invocation signature of parent roles. Additionally, …
9213 msgid "In addition to the above, users should be aware that role de-duplication occurs before varia…
9217 msgid "For example, a role named ``car`` depends on a role named ``wheel`` as follows:"
9221 msgid "And the ``wheel`` role depends on two roles: ``tire`` and ``brake``. The ``meta/main.yml`` f…
9225 msgid "And the ``meta/main.yml`` for ``tire`` and ``brake`` would contain the following:"
9229 msgid "The resulting order of execution would be as follows:"
9233 msgid "To use ``allow_duplicates: true`` with role dependencies, you must specify it for the role l…
9237 msgid "See :ref:`playbooks_variables` for details on how Ansible chooses among variable values defi…
9241 msgid "Embedding modules and plugins in roles"
9245 msgid "If you write a custom module (see :ref:`developing_modules`) or a plugin (see :ref:`developi…
9249 msgid "To add a module or a plugin to a role: Alongside the 'tasks' and 'handlers' structure of a r…
9253 msgid "Assuming you had this:"
9257 msgid "The module will be usable in the role itself, as well as any roles that are called *after* t…
9261 msgid "If necessary, you can also embed a module in a role to modify a module in Ansible's core dis…
9265 msgid "The same mechanism can be used to embed and distribute plugins in a role, using the same sch…
9269 msgid "These filters can then be used in a Jinja template in any role called after 'my_custom_filte…
9273 msgid "Sharing roles: Ansible Galaxy"
9277 msgid "`Ansible Galaxy <https://galaxy.ansible.com>`_ is a free site for finding, downloading, rati…
9281 msgid "The client ``ansible-galaxy`` is included in Ansible. The Galaxy client allows you to downlo…
9285 msgid "Read the `Ansible Galaxy documentation <https://galaxy.ansible.com/docs/>`_ page for more in…
9289 msgid "How to create new roles, share roles on Galaxy, role management"
9293 msgid "Variables in playbooks"
9297 msgid ":ref:`tags`"
9301 msgid "Using tags to select or skip roles/tasks in long playbooks"
9305 msgid "Extending Ansible by writing your own modules"
9309 msgid "Playbook Roles and Include Statements"
9313 msgid "The documentation regarding roles and includes for playbooks have moved. Their new location …
9317 msgid ":ref:`playbooks_reuse`"
9321 msgid "Creating reusable Playbooks."
9325 msgid "Advanced playbooks features"
9329 msgid "This page is obsolete. Refer to the :ref:`main User Guide index page <user_guide_index>` for…
9333 msgid "Executing playbooks for troubleshooting"
9337 msgid "When you are testing new plays or debugging playbooks, you may need to run the same play mul…
9341 msgid "start-at-task"
9345 msgid "To start executing your playbook at a particular task (usually the task that failed on the p…
9349 msgid "In this example, Ansible starts executing your playbook at a task named \"install packages\"…
9353 msgid "Step mode"
9357 msgid "To execute a playbook interactively, use ``--step``::"
9361 msgid "With this option, Ansible stops on each task, and asks if it should execute that task. For e…
9365 msgid "Answer \"y\" to execute the task, answer \"n\" to skip the task, and answer \"c\" to exit st…
9369 msgid ":ref:`playbook_debugger`"
9373 msgid "Using the Ansible debugger"
9377 msgid "Controlling playbook execution: strategies and more"
9381 msgid "By default, Ansible runs each task on all hosts affected by a play before starting the next …
9385 msgid "Selecting a strategy"
9389 msgid "The default behavior described above is the :ref:`linear strategy<linear_strategy>`. Ansible…
9393 msgid "You can select a different strategy for each play as shown above, or set your preferred stra…
9397 msgid "All strategies are implemented as :ref:`strategy plugins<strategy_plugins>`. Please review t…
9401 msgid "Setting the number of forks"
9405 msgid "If you have the processing power available and want to use more forks, you can set the numbe…
9409 msgid "or pass it on the command line: `ansible-playbook -f 30 my_playbook.yml`."
9413 msgid "Using keywords to control execution"
9417 msgid "In addition to strategies, several :ref:`keywords<playbook_keywords>` also affect play execu…
9421 msgid "Setting the batch size with ``serial``"
9425 msgid "By default, Ansible runs in parallel against all the hosts in the :ref:`pattern <intro_patte…
9429 msgid "In the above example, if we had 6 hosts in the group 'webservers', Ansible would execute the…
9433 msgid "You can also specify a percentage with the ``serial`` keyword. Ansible applies the percentag…
9437 msgid "If the number of hosts does not divide equally into the number of passes, the final pass con…
9441 msgid "You can also specify batch sizes as a list. For example::"
9445 msgid "In the above example, the first batch would contain a single host, the next would contain 5 …
9449 msgid "You can list multiple batch sizes as percentages::"
9453 msgid "You can also mix and match the values::"
9457 msgid "No matter how small the percentage, the number of hosts per pass will always be 1 or greater…
9461 msgid "Restricting execution with ``throttle``"
9465 msgid "The ``throttle`` keyword limits the number of workers for a particular task. It can be set a…
9469 msgid "If you have already restricted the number of forks or the number of machines to execute agai…
9473 msgid "Ordering execution based on inventory"
9477 msgid "The ``order`` keyword controls the order in which hosts are run. Possible values for order a…
9481 msgid "inventory:"
9485 msgid "(default) The order provided in the inventory"
9489 msgid "reverse_inventory:"
9493 msgid "The reverse of the order provided by the inventory"
9497 msgid "sorted:"
9501 msgid "Sorted alphabetically sorted by name"
9505 msgid "reverse_sorted:"
9509 msgid "Sorted by name in reverse alphabetical order"
9513 msgid "shuffle:"
9517 msgid "Randomly ordered on each run"
9521 msgid "Other keywords that affect play execution include ``ignore_errors``, ``ignore_unreachable``,…
9525 msgid "Running on a single machine with ``run_once``"
9529 msgid "If you want a task to run only on the first host in your batch of hosts, set ``run_once`` to…
9533 msgid "Ansible executes this task on the first host in the current batch and applies all results an…
9537 msgid "However, with ``run_once``, the results are applied to all the hosts. To run the task on a s…
9541 msgid "As always with :ref:`delegation <playbooks_delegation>`, the action will be executed on the …
9545 msgid "When used together with ``serial``, tasks marked as ``run_once`` will be run on one host in …
9549 msgid "Any conditional (in other words, `when:`) will use the variables of the 'first host' to deci…
9553 msgid "If you want to avoid the default behavior of setting the fact for all hosts, set ``delegate_…
9557 msgid ":ref:`playbooks_delegation`"
9561 msgid "Running tasks on or assigning facts to specific machines"
9565 msgid "Tags"
9569 msgid "If you have a large playbook, it may be useful to run only specific parts of it instead of r…
9573 msgid "Add tags to your tasks, either individually or with tag inheritance from a block, play, role…
9577 msgid "Select or skip tags when you run your playbook."
9581 msgid "Adding tags with the tags keyword"
9585 msgid "You can add tags to a single task or include. You can also add tags to multiple tasks by def…
9589 msgid "Adding tags to individual tasks"
9593 msgid "At the simplest level, you can apply one or more tags to an individual task. You can add tag…
9597 msgid "You can apply the same tag to more than one individual task. This example tags several tasks…
9601 msgid "If you ran these four tasks in a playbook with ``--tags ntp``, Ansible would run the three t…
9605 msgid "Adding tags to includes"
9609 msgid "You can apply tags to dynamic includes in a playbook. As with tags on an individual task, ta…
9613 msgid "You add tags to includes the same way you add tags to any other task:"
9617 msgid "You can add a tag only to the dynamic include of a role. In this example, the ``foo`` tag wi…
9621 msgid "With plays, blocks, the ``role`` keyword, and static imports, Ansible applies tag inheritanc…
9625 msgid "Tag inheritance: adding tags to multiple tasks"
9629 msgid "If you want to apply the same tag or tags to multiple tasks without adding a ``tags`` line t…
9633 msgid "Adding tags to blocks"
9637 msgid "If you want to apply a tag to many, but not all, of the tasks in your play, use a :ref:`bloc…
9641 msgid "Adding tags to plays"
9645 msgid "If all the tasks in a play should get the same tag, you can add the tag at the level of the …
9649 msgid "Adding tags to roles"
9653 msgid "There are three ways to add tags to roles:"
9657 msgid "Add the same tag or tags to all tasks in the role by setting tags under ``roles``. See examp…
9661 msgid "Add the same tag or tags to all tasks in the role by setting tags on a static ``import_role`…
9665 msgid "Add a tag or tags to individual tasks or blocks within the role itself. This is the only app…
9669 msgid "When you incorporate a role in your playbook statically with the ``roles`` keyword, Ansible …
9673 msgid "or:"
9677 msgid "Adding tags to imports"
9681 msgid "You can also apply a tag or tags to all the tasks imported by the static ``import_role`` and…
9685 msgid "Tag inheritance for includes: blocks and the ``apply`` keyword"
9689 msgid "By default, Ansible does not apply :ref:`tag inheritance <tag_inheritance>` to dynamic re-us…
9693 msgid "If you want tag inheritance, you probably want to use imports. However, using both includes …
9697 msgid "Or you can use a block:"
9701 msgid "Special tags: always and never"
9705 msgid "Ansible reserves two tag names for special behavior: always and never. If you assign the ``a…
9710 msgid "For example:"
9714 msgid "Fact gathering is tagged with 'always' by default. It is only skipped if you apply a tag and…
9718 msgid "The role argument specification validation task is tagged with 'always' by default. This val…
9722 msgid "If you assign the ``never`` tag to a task or play, Ansible will skip that task or play unles…
9726 msgid "The rarely-used debug task in the example above only runs when you specifically request the …
9730 msgid "Selecting or skipping tags when you run a playbook"
9734 msgid "Once you have added tags to your tasks, includes, blocks, plays, roles, and imports, you can…
9738 msgid ":ref:`ansible-playbook` offers five tag-related command-line options:"
9742 msgid "``--tags all`` - run all tasks, ignore tags (default behavior)"
9746 msgid "``--tags [tag1, tag2]`` - run only tasks with either the tag ``tag1`` or the tag ``tag2``"
9750 msgid "``--skip-tags [tag3, tag4]`` - run all tasks except those with either the tag ``tag3`` or th…
9754 msgid "``--tags tagged`` - run only tasks with at least one tag"
9758 msgid "``--tags untagged`` - run only tasks with no tags"
9762 msgid "For example, to run only tasks and blocks tagged ``configuration`` and ``packages`` in a ver…
9766 msgid "To run all tasks except those tagged ``packages``:"
9770 msgid "Previewing the results of using tags"
9774 msgid "When you run a role or playbook, you might not know or remember which tasks have which tags,…
9778 msgid "``--list-tags`` - generate a list of available tags"
9782 msgid "``--list-tasks`` - when used with ``--tags tagname`` or ``--skip-tags tagname``, generate a …
9786 msgid "For example, if you do not know whether the tag for configuration tasks is ``config`` or ``c…
9790 msgid "If you do not know which tasks have the tags ``configuration`` and ``packages``, you can pas…
9794 msgid "These command-line flags have one limitation: they cannot show tags or tasks within dynamica…
9798 msgid "Selectively running tagged tasks in re-usable files"
9802 msgid "If you have a role or a tasks file with tags defined at the task or block level, you can sel…
9806 msgid "And you might include the tasks file above in a playbook:"
9810 msgid "When you run the playbook with ``ansible-playbook -i hosts myplaybook.yml --tags \"mytag\"``…
9814 msgid "Configuring tags globally"
9818 msgid "If you run or skip certain tags by default, you can use the :ref:`TAGS_RUN` and :ref:`TAGS_S…
9822 msgid "Templating (Jinja2)"
9826 msgid "Ansible uses Jinja2 templating to enable dynamic expressions and access to variables. Ansibl…
9830 msgid "All templating happens on the Ansible controller **before** the task is sent and executed on…
9834 msgid "Get the current time"
9838 msgid "The ``now()`` Jinja2 function retrieves a Python datetime object or a string representation …
9842 msgid "The ``now()`` function supports 2 arguments:"
9846 msgid "utc"
9850 msgid "Specify ``True`` to get the current time in UTC. Defaults to ``False``."
9854 msgid "fmt"
9858 msgid "Accepts a `strftime <https://docs.python.org/3/library/datetime.html#strftime-strptime-behav…
9862 msgid "Tests"
9866 msgid "`Tests <http://jinja.pocoo.org/docs/dev/templates/#tests>`_ in Jinja are a way of evaluating…
9870 msgid "The main difference between tests and filters are that Jinja tests are used for comparisons,…
9874 msgid "Like all templating, tests always execute on the Ansible controller, **not** on the target o…
9878 msgid "In addition to those Jinja2 tests, Ansible supplies a few more and users can easily create t…
9882 msgid "Test syntax"
9886 msgid "`Test syntax <http://jinja.pocoo.org/docs/dev/templates/#tests>`_ varies from `filter syntax…
9890 msgid "As of Ansible 2.5, using a jinja test as a filter will generate a warning."
9894 msgid "The syntax for using a jinja test is as follows::"
9898 msgid "Such as::"
9902 msgid "Testing strings"
9906 msgid "To match strings against a substring or a regular expression, use the ``match``, ``search`` …
9910 msgid "``match`` succeeds if it finds the pattern at the beginning of the string, while ``search`` …
9914 msgid "All of the string tests also take optional ``ignorecase`` and ``multiline`` arguments. These…
9918 msgid "Vault"
9922 msgid "You can test whether a variable is an inline single vault encrypted value using the ``vault_…
9926 msgid "Testing truthiness"
9930 msgid "As of Ansible 2.10, you can now perform Python like truthy and falsy checks."
9934 msgid "Additionally, the ``truthy`` and ``falsy`` tests accept an optional parameter called ``conve…
9938 msgid "Comparing versions"
9942 msgid "In 2.5 ``version_compare`` was renamed to ``version``"
9946 msgid "To compare a version number, such as checking if the ``ansible_facts['distribution_version']…
9950 msgid "The ``version`` test can also be used to evaluate the ``ansible_facts['distribution_version'…
9954 msgid "If ``ansible_facts['distribution_version']`` is greater than or equal to 12.04, this test re…
9958 msgid "The ``version`` test accepts the following operators::"
9962 msgid "This test also accepts a 3rd parameter, ``strict`` which defines if strict version parsing a…
9966 msgid "As of Ansible 2.11 the ``version`` test accepts a ``version_type`` parameter which is mutual…
9970 msgid "Using ``version_type`` to compare a semantic version would be achieved like the following::"
9974 msgid "When using ``version`` in a playbook or role, don't use ``{{ }}`` as described in the `FAQ <…
9978 msgid "Set theory tests"
9982 msgid "In 2.5 ``issubset`` and ``issuperset`` were renamed to ``subset`` and ``superset``"
9986 msgid "To see if a list includes or is included by another list, you can use 'subset' and 'superset…
9990 msgid "Testing if a list contains a value"
9994 msgid "Ansible includes a ``contains`` test which operates similarly, but in reverse of the Jinja2 …
9998 msgid "Testing if a list value is True"
10002 msgid "You can use `any` and `all` to check if any or all elements in a list are true or not::"
10006 msgid "Testing paths"
10010 msgid "In 2.5 the following tests were renamed to remove the ``is_`` prefix"
10014 msgid "The following tests can provide information about a path on the controller::"
10018 msgid "Testing size formats"
10022 msgid "The ``human_readable`` and ``human_to_bytes`` functions let you test your playbooks to make …
10026 msgid "Human readable"
10030 msgid "Asserts whether the given string is human readable or not."
10034 msgid "Human to bytes"
10038 msgid "Returns the given string in the Bytes format."
10042 msgid "Testing task results"
10046 msgid "The following tasks are illustrative of the tests meant to check the status of tasks::"
10050 msgid "From 2.1, you can also use success, failure, change, and skip so that the grammar matches, f…
10054 msgid "Using Variables"
10058 msgid "Ansible uses variables to manage differences between systems. With Ansible, you can execute …
10062 msgid "After you create variables, either by defining them in a file, passing them at the command l…
10066 msgid "Once you understand the concepts and examples on this page, read about :ref:`Ansible facts <…
10070 msgid "Creating valid variable names"
10074 msgid "Not all strings are valid Ansible variable names. A variable name can only include letters, …
10078 msgid "Variable names can begin with an underscore. In many programming languages, variables that b…
10082 msgid "This table gives examples of valid and invalid variable names:"
10086 msgid "Valid variable names"
10090 msgid "Not valid"
10094 msgid "``foo``"
10098 msgid "``*foo``, `Python keywords`_ such as ``async`` and ``lambda``"
10102 msgid "``foo_env``"
10106 msgid ":ref:`playbook keywords<playbook_keywords>` such as ``environment``"
10110 msgid "``foo_port``"
10114 msgid "``foo-port``, ``foo port``, ``foo.port``"
10118 msgid "``foo5``, ``_foo``"
10122 msgid "``5foo``, ``12``"
10126 msgid "Simple variables"
10130 msgid "Simple variables combine a variable name with a single value. You can use this syntax (and t…
10134 msgid "Defining simple variables"
10138 msgid "You can define a simple variable using standard YAML syntax. For example::"
10142 msgid "Referencing simple variables"
10146 msgid "After you define a variable, use Jinja2 syntax to reference it. Jinja2 variables use double …
10150 msgid "In this example, the variable defines the location of a file, which can vary from one system…
10154 msgid "Ansible allows Jinja2 loops and conditionals in :ref:`templates <playbooks_templating>` but …
10158 msgid "When to quote variables (a YAML gotcha)"
10162 msgid "If you start a value with ``{{ foo }}``, you must quote the whole expression to create valid…
10166 msgid "If you use a variable without quotes like this::"
10170 msgid "You will see: ``ERROR! Syntax Error while loading YAML.`` If you add quotes, Ansible works c…
10174 msgid "List variables"
10178 msgid "A list variable combines a variable name with multiple values. The multiple values can be st…
10182 msgid "Defining variables as lists"
10186 msgid "You can define variables with multiple values using YAML lists. For example::"
10190 msgid "Referencing list variables"
10194 msgid "When you use variables defined as a list (also called an array), you can use individual, spe…
10198 msgid "The value of this expression would be \"northeast\"."
10202 msgid "Dictionary variables"
10206 msgid "A dictionary stores the data in key-value pairs. Usually, dictionaries are used to store rel…
10210 msgid "Defining variables as key:value dictionaries"
10214 msgid "You can define more complex variables using YAML dictionaries. A YAML dictionary maps keys t…
10218 msgid "Referencing key:value dictionary variables"
10222 msgid "When you use variables defined as a key:value dictionary (also called a hash), you can use i…
10226 msgid "Both of these examples reference the same value (\"one\"). Bracket notation always works. Do…
10230 msgid "``add``, ``append``, ``as_integer_ratio``, ``bit_length``, ``capitalize``, ``center``, ``cle…
10234 msgid "Registering variables"
10238 msgid "You can create variables from the output of an Ansible task with the task keyword ``register…
10242 msgid "For more examples of using registered variables in conditions on later tasks, see :ref:`play…
10246 msgid "Registered variables are stored in memory. You cannot cache registered variables for use in …
10250 msgid "Registered variables are host-level variables. When you register a variable in a task with a…
10254 msgid "If a task fails or is skipped, Ansible still registers a variable with a failure or skipped …
10258 msgid "Referencing nested variables"
10262 msgid "Many registered variables (and :ref:`facts <vars_and_facts>`) are nested YAML or JSON data s…
10266 msgid "To reference an IP address from your facts using the dot notation::"
10270 msgid "Transforming variables with Jinja2 filters"
10274 msgid "Jinja2 filters let you transform the value of a variable within a template expression. For e…
10278 msgid "Where to set variables"
10282 msgid "You can define variables in a variety of places, such as in inventory, in playbooks, in reus…
10286 msgid "Defining variables in inventory"
10290 msgid "You can define different variables for each individual host, or set shared variables for a g…
10294 msgid "Defining variables in a play"
10298 msgid "You can define variables directly in a playbook play::"
10302 msgid "When you define variables in a play, they are only visible to tasks executed in that play."
10306 msgid "Defining variables in included files and roles"
10310 msgid "You can define variables in reusable variables files and/or in reusable roles. When you defi…
10314 msgid "This example shows how you can include variables defined in an external file::"
10318 msgid "The contents of each variables file is a simple YAML dictionary. For example::"
10322 msgid "You can keep per-host and per-group variables in similar files. To learn about organizing yo…
10326 msgid "Defining variables at runtime"
10330 msgid "You can define variables when you run your playbook by passing variables at the command line…
10334 msgid "key=value format"
10338 msgid "Values passed in using the ``key=value`` syntax are interpreted as strings. Use the JSON for…
10342 msgid "JSON string format"
10346 msgid "When passing variables with ``--extra-vars``, you must escape quotes and other special chara…
10350 msgid "If you have a lot of special characters, use a JSON or YAML file containing the variable def…
10354 msgid "vars from a JSON or YAML file"
10358 msgid "Variable precedence: Where should I put a variable?"
10362 msgid "You can set multiple variables with the same name in many different places. When you do this…
10366 msgid "Teams and projects that agree on guidelines for defining variables (where to define certain …
10370 msgid "Some behavioral parameters that you can set in variables you can also set in Ansible configu…
10374 msgid "Understanding variable precedence"
10378 msgid "Ansible does apply variable precedence, and you might have a use for it. Here is the order o…
10382 msgid "command line values (for example, ``-u my_user``, these are not variables)"
10386 msgid "role defaults (defined in role/defaults/main.yml) [1]_"
10390 msgid "inventory file or script group vars [2]_"
10394 msgid "inventory group_vars/all [3]_"
10398 msgid "playbook group_vars/all [3]_"
10402 msgid "inventory group_vars/* [3]_"
10406 msgid "playbook group_vars/* [3]_"
10410 msgid "inventory file or script host vars [2]_"
10414 msgid "inventory host_vars/* [3]_"
10418 msgid "playbook host_vars/* [3]_"
10422 msgid "host facts / cached set_facts [4]_"
10426 msgid "play vars"
10430 msgid "play vars_prompt"
10434 msgid "play vars_files"
10438 msgid "role vars (defined in role/vars/main.yml)"
10442 msgid "block vars (only for tasks in block)"
10446 msgid "task vars (only for the task)"
10451 msgid "include_vars"
10455 msgid "set_facts / registered vars"
10459 msgid "role (and include_role) params"
10463 msgid "include params"
10467 msgid "extra vars (for example, ``-e \"user=my_user\"``)(always win precedence)"
10471 msgid "In general, Ansible gives precedence to variables that were defined more recently, more acti…
10475 msgid "Ansible merges different variables set in inventory so that more specific settings override …
10479 msgid "Footnotes"
10483 msgid "Tasks in each role see their own role's defaults. Tasks defined outside of a role see the la…
10487 msgid "Variables defined in inventory file or provided by dynamic inventory."
10491 msgid "Includes vars added by 'vars plugins' as well as host_vars and group_vars which are added by…
10495 msgid "When created with set_facts's cacheable option, variables have the high precedence in the pl…
10499 msgid "Within any section, redefining a var overrides the previous instance. If multiple groups hav…
10503 msgid "The previous describes the default config ``hash_behaviour=replace``, switch to ``merge`` to…
10507 msgid "Scoping variables"
10511 msgid "You can decide where to set a variable based on the scope you want that value to have. Ansib…
10515 msgid "Global: this is set by config, environment variables and the command line"
10519 msgid "Play: each play and contained structures, vars entries (vars; vars_files; vars_prompt), role…
10523 msgid "Host: variables directly associated to a host, like inventory, include_vars, facts or regist…
10527 msgid "Inside a template, you automatically have access to all variables that are in scope for a ho…
10531 msgid "Tips on where to set variables"
10535 msgid "You should choose where to define a variable based on the kind of control you might want ove…
10539 msgid "Set variables in inventory that deal with geography or behavior. Since groups are frequently…
10543 msgid "Set common defaults in a ``group_vars/all`` file. See :ref:`splitting_out_vars` for details …
10547 msgid "Set location-specific variables in ``group_vars/my_location`` files. All groups are children…
10551 msgid "If one host used a different NTP server, you could set that in a host_vars file, which would…
10555 msgid "Set defaults in roles to avoid undefined-variable errors. If you share your roles, other use…
10559 msgid "Set variables in roles to ensure a value is used in that role, and is not overridden by inve…
10563 msgid "Pass variables as parameters when you call roles for maximum clarity, flexibility, and visib…
10567 msgid "When you read this playbook it is clear that you have chosen to set a variable or override a…
10571 msgid "Variables set in one role are available to later roles. You can set variables in a ``roles/c…
10575 msgid "There are some protections in place to avoid the need to namespace variables. In this exampl…
10579 msgid "Instead of worrying about variable precedence, we encourage you to think about how easily or…
10583 msgid "Using advanced variable syntax"
10587 msgid "For information about advanced YAML syntax used to declare variables and have more control o…
10591 msgid "Jinja2 filters and their uses"
10595 msgid ":ref:`special_variables`"
10599 msgid "List of special variables"
10603 msgid "Discovering variables: facts and magic variables"
10607 msgid "With Ansible you can retrieve or discover certain variables containing information about you…
10611 msgid "Ansible facts"
10615 msgid "Ansible facts are data related to your remote systems, including operating systems, IP addre…
10619 msgid "To see the 'raw' information as gathered, run this command at the command line::"
10623 msgid "Facts include a large amount of variable data, which may look like this:"
10627 msgid "You can reference the model of the first disk in the facts shown above in a template or play…
10631 msgid "To reference the system hostname::"
10635 msgid "You can use facts in conditionals (see :ref:`playbooks_conditionals`) and also in templates.…
10639 msgid "Package requirements for fact gathering"
10643 msgid "On some distros, you may see missing fact values or facts set to default values because the …
10647 msgid "Linux Network fact gathering -  Depends on  the ``ip`` binary, commonly included in the ``ip…
10651 msgid "Caching facts"
10655 msgid "Like registered variables, facts are stored in memory by default. However, unlike registered…
10659 msgid "Caching is controlled by the cache plugins. By default, Ansible uses the memory cache plugin…
10663 msgid "Fact caching can improve performance. If you manage thousands of hosts, you can configure fa…
10667 msgid "Disabling facts"
10671 msgid "By default, Ansible gathers facts at the beginning of each play. If you do not need to gathe…
10675 msgid "Adding custom facts"
10679 msgid "The setup module in Ansible automatically discovers a standard set of facts about each host.…
10683 msgid "facts.d or local facts"
10687 msgid "You can add static custom facts by adding static files to facts.d, or add dynamic facts by a…
10691 msgid "To use facts.d, create an ``/usr/local/etc/ansible/facts.d`` directory on the remote host or…
10695 msgid "To add static facts, simply add a file with the ``.fact`` extension. For example, create ``/…
10699 msgid "Make sure the file is not executable as this will break the ``ansible.builtin.setup`` module…
10703 msgid "The next time fact gathering runs, your facts will include a hash variable fact named ``gene…
10707 msgid "And you will see your custom fact added::"
10711 msgid "The ansible_local namespace separates custom facts created by facts.d from system facts or v…
10715 msgid "The key part in the key=value pairs will be converted into lowercase inside the ansible_loca…
10719 msgid "You can also use facts.d to execute a script on the remote host, generating dynamic custom f…
10723 msgid "Write and test a script to generate the JSON data you want."
10727 msgid "Save the script in your facts.d directory."
10731 msgid "Make sure your script has the ``.fact`` file extension."
10735 msgid "Make sure your script is executable by the Ansible connection user."
10739 msgid "Gather facts to execute the script and add the JSON output to ansible_local."
10743 msgid "By default, fact gathering runs once at the beginning of each play. If you create a custom f…
10747 msgid "If you use this pattern frequently, a custom facts module would be more efficient than facts…
10751 msgid "Information about Ansible: magic variables"
10755 msgid "You can access information about Ansible operations, including the python version being used…
10759 msgid "The most commonly used magic variables are ``hostvars``, ``groups``, ``group_names``, and ``…
10763 msgid "If you want to configure your database server using the value of a 'fact' from another node,…
10767 msgid "With ``groups``, a list of all the groups (and hosts) in the inventory, you can enumerate al…
10771 msgid "You can use ``groups`` and ``hostvars`` together to find all the IP addresses in a group."
10775 msgid "You can use this approach to point a frontend proxy server to all the hosts in your app serv…
10779 msgid "With ``group_names``, a list (array) of all the groups the current host is in, you can creat…
10783 msgid "You can use the magic variable ``inventory_hostname``, the name of the host as configured in…
10787 msgid "Other useful magic variables refer to the current play or playbook. These vars may be useful…
10791 msgid "``ansible_play_hosts`` is the list of all hosts still active in the current play."
10795 msgid "``ansible_play_batch`` is a list of hostnames that are in scope for the current 'batch' of t…
10799 msgid "The batch size is defined by ``serial``, when not set it is equivalent to the whole play (ma…
10803 msgid "``ansible_playbook_python`` is the path to the python executable used to invoke the Ansible …
10807 msgid "``inventory_dir`` is the pathname of the directory holding Ansible's inventory host file."
10811 msgid "``inventory_file`` is the pathname and the filename pointing to the Ansible's inventory host…
10815 msgid "``playbook_dir`` contains the playbook base directory."
10819 msgid "``role_path`` contains the current role's pathname and only works inside a role."
10823 msgid "``ansible_check_mode`` is a boolean, set to ``True`` if you run Ansible with ``--check``."
10827 msgid "Ansible version"
10831 msgid "To adapt playbook behavior to different versions of Ansible, you can use the variable ``ansi…
10835 msgid "Using vault in playbooks"
10839 msgid "The documentation regarding Ansible Vault has moved. The new location is here: :ref:`vault`.…
10843 msgid "Rejecting modules"
10847 msgid "If you want to avoid using certain modules, you can add them to a reject list to prevent Ans…
10851 msgid "The file contains two fields:"
10855 msgid "A file version so that you can update the format while keeping backwards compatibility in th…
10859 msgid "A list of modules to reject. Ansible will not load any module in this list when it searches …
10863 msgid "The ``stat`` module is required for Ansible to run. Do not add this module to your reject li…
10867 msgid "Ansible Quickstart Guide"
10871 msgid "We've recorded a short video that introduces Ansible."
10875 msgid "The `quickstart video <https://www.ansible.com/resources/videos/quick-start-video>`_ is abou…
10879 msgid "Enjoy, and be sure to visit the rest of the documentation to learn more."
10883 msgid "`A system administrators guide to getting started with Ansible <https://www.redhat.com/en/bl…
10887 msgid "A step by step introduction to Ansible"
10891 msgid "`Ansible Automation for SysAdmins <https://opensource.com/downloads/ansible-quickstart>`_"
10895 msgid "A downloadable guide for getting started with Ansible"
10899 msgid ":ref:`network_getting_started`"
10903 msgid "A guide for network engineers using Ansible for the first time"
10907 msgid "Sample Ansible setup"
10911 msgid "You have learned about playbooks, inventory, roles, and variables. This section pulls all th…
10915 msgid "The sample setup organizes playbooks, roles, inventory, and variables files by function, wit…
10919 msgid "Sample directory layout"
10923 msgid "This layout organizes most tasks in roles, with a single inventory file for each environment…
10927 msgid "Alternative directory layout"
10931 msgid "Alternatively you can put each inventory file with its ``group_vars``/``host_vars`` in a sep…
10935 msgid "This layout gives you more flexibility for larger environments, as well as a total separatio…
10939 msgid "Sample group and host variables"
10943 msgid "These sample group and host variables files record the variable values that apply to each ma…
10947 msgid "Similarly, the webservers have some configuration that does not apply to the database server…
10951 msgid "Default values, or values that are universally true, belong in a file called group_vars/all:…
10955 msgid "If necessary, you can define specific hardware variance in systems in a host_vars file::"
10959 msgid "Again, if you are using :ref:`dynamic inventory <dynamic_inventory>`, Ansible creates many d…
10963 msgid "Sample playbooks organized by function"
10967 msgid "With this setup, a single playbook can define all the infrastructure. The site.yml playbook …
10971 msgid "The webservers.yml file, also at the top level, maps the configuration of the webservers gro…
10975 msgid "With this setup, you can configure your whole infrastructure by \"running\" site.yml, or run…
10979 msgid "Sample task and handler files in a function-based role"
10983 msgid "Ansible loads any file called ``main.yml`` in a role sub-directory. This sample ``tasks/main…
10987 msgid "Here is an example handlers file.  As a review, handlers are only fired when certain tasks r…
10991 msgid "See :ref:`playbooks_reuse_roles` for more information."
10995 msgid "What the sample setup enables"
10999 msgid "The basic organizational structure described above enables a lot of different automation opt…
11003 msgid "To reconfigure NTP on everything::"
11007 msgid "To reconfigure only the webservers::"
11011 msgid "To reconfigure only the webservers in Boston::"
11015 msgid "To reconfigure only the first 10 webservers in Boston, and then the next 10::"
11019 msgid "The sample setup also supports basic ad hoc commands::"
11023 msgid "To discover what tasks would run or what hostnames would be affected by a particular Ansible…
11027 msgid "Organizing for deployment or configuration"
11031 msgid "The sample setup models a typical configuration topology.  When doing multi-tier deployments…
11035 msgid "Consider \"playbooks\" as a sports metaphor -- you can have one set of plays to use against …
11039 msgid "Using local Ansible modules"
11043 msgid "If a playbook has a :file:`./library` directory relative to its YAML file, this directory ca…
11047 msgid "Encrypting content with Ansible Vault"
11051 msgid "Ansible Vault encrypts variables and files so you can protect sensitive content such as pass…
11055 msgid "Encryption with Ansible Vault ONLY protects 'data at rest'.  Once the content is decrypted (…
11059 msgid "You can use encrypted variables and files in ad hoc commands and playbooks by supplying the …
11063 msgid "Managing vault passwords"
11067 msgid "Managing your encrypted content is easier if you develop a strategy for managing your vault …
11071 msgid "Do you want to encrypt all your content with the same password, or use different passwords f…
11075 msgid "Where do you want to store your password or passwords?"
11079 msgid "Choosing between a single password and multiple passwords"
11083 msgid "If you have a small team or few sensitive values, you can use a single password for everythi…
11087 msgid "If you have a larger team or many sensitive values, you can use multiple passwords. For exam…
11091 msgid "Managing multiple passwords with vault IDs"
11095 msgid "If you use multiple vault passwords, you can differentiate one password from another with va…
11099 msgid "Pass it with :option:`--vault-id <ansible-playbook --vault-id>` to the :ref:`ansible-vault` …
11103 msgid "Include it wherever you store the password for that vault ID (see :ref:`storing_vault_passwo…
11107 msgid "Pass it with :option:`--vault-id <ansible-playbook --vault-id>` to the :ref:`ansible-playboo…
11111 msgid "When you pass a vault ID as an option to the :ref:`ansible-vault` command, you add a label (…
11115 msgid "In addition to the label, you must provide a source for the related password. The source can…
11119 msgid "If your playbook uses multiple encrypted variables or files that you encrypted with differen…
11123 msgid "See below for examples of encrypting content with vault IDs and using content encrypted with…
11127 msgid "Limitations of vault IDs"
11131 msgid "Ansible does not enforce using the same password every time you use a particular vault ID la…
11135 msgid "Enforcing vault ID matching"
11139 msgid "By default the vault ID label is only a hint to remind you which password you used to encryp…
11143 msgid "Even with the :ref:`DEFAULT_VAULT_ID_MATCH` setting enabled, Ansible does not enforce using …
11147 msgid "Storing and accessing vault passwords"
11151 msgid "You can memorize your vault password, or manually copy vault passwords from any source and p…
11155 msgid "Storing passwords in files"
11159 msgid "To store a vault password in a file, enter the password as a string on a single line in the …
11163 msgid "Storing passwords in third-party tools with vault password client scripts"
11167 msgid "You can store your vault passwords on the system keyring, in a database, or in a secret mana…
11171 msgid "To create a vault password client script:"
11175 msgid "Create a file with a name ending in either ``-client`` or ``-client.EXTENSION``"
11179 msgid "Make the file executable"
11183 msgid "Within the script itself:"
11187 msgid "Print the passwords to standard output"
11191 msgid "Accept a ``--vault-id`` option"
11195 msgid "If the script prompts for data (for example, a database password), send the prompts to stand…
11199 msgid "When you run a playbook that uses vault passwords stored in a third-party tool, specify the …
11203 msgid "Ansible executes the client script with a ``--vault-id`` option so the script knows which va…
11207 msgid "For an example of a client script that loads passwords from the system keyring, see :file:`c…
11211 msgid "Once you have a strategy for managing and storing vault passwords, you can start encrypting …
11215 msgid "Encrypted variables"
11219 msgid "Encrypted files"
11223 msgid "How much is encrypted?"
11227 msgid "Variables within a plaintext file"
11231 msgid "The entire file"
11235 msgid "When is it decrypted?"
11239 msgid "On demand, only when needed"
11243 msgid "Whenever loaded or referenced [#f1]_"
11247 msgid "What can be encrypted?"
11251 msgid "Only variables"
11255 msgid "Any structured data file"
11259 msgid "Ansible cannot know if it needs content from an encrypted file unless it decrypts the file, …
11263 msgid "Encrypting individual variables with Ansible Vault"
11267 msgid "You can encrypt single values inside a YAML file using the :ref:`ansible-vault encrypt_strin…
11271 msgid "Advantages and disadvantages of encrypting variables"
11275 msgid "With variable-level encryption, your files are still easily legible. You can mix plaintext a…
11279 msgid "Creating encrypted variables"
11283 msgid "The :ref:`ansible-vault encrypt_string <ansible_vault_encrypt_string>` command encrypts and …
11287 msgid "a source for the vault password (prompt, file, or script, with or without a vault ID)"
11291 msgid "the string to encrypt"
11295 msgid "the string name (the name of the variable)"
11299 msgid "The pattern looks like this:"
11303 msgid "For example, to encrypt the string 'foobar' using the only password stored in 'a_password_fi…
11307 msgid "The command above creates this content::"
11311 msgid "To encrypt the string 'foooodev', add the vault ID label 'dev' with the 'dev' vault password…
11315 msgid "To encrypt the string 'letmein' read from stdin, add the vault ID 'dev' using the 'dev' vaul…
11319 msgid "Typing secret content directly at the command line (without a prompt) leaves the secret stri…
11323 msgid "The command above creates this output::"
11327 msgid "To be prompted for a string to encrypt, encrypt it with the 'dev' vault password from 'a_pas…
11331 msgid "The command above triggers this prompt:"
11335 msgid "Type the string to encrypt (for example, 'hunter2'), hit ctrl-d, and wait."
11339 msgid "Do not press ``Enter`` after supplying the string to encrypt. That will add a newline to the…
11343 msgid "The sequence above creates this output::"
11347 msgid "You can add the output from any of the examples above to any playbook, variables file, or ro…
11351 msgid "Viewing encrypted variables"
11355 msgid "You can view the original value of an encrypted variable using the debug module. You must pa…
11359 msgid "Encrypting files with Ansible Vault"
11363 msgid "Ansible Vault can encrypt any structured data file used by Ansible, including:"
11367 msgid "group variables files from inventory"
11371 msgid "host variables files from inventory"
11375 msgid "variables files passed to ansible-playbook with ``-e @file.yml`` or ``-e @file.json``"
11379 msgid "variables files loaded by ``include_vars`` or ``vars_files``"
11383 msgid "variables files in roles"
11387 msgid "defaults files in roles"
11391 msgid "tasks files"
11395 msgid "handlers files"
11399 msgid "binary files or other arbitrary files"
11403 msgid "The full file is encrypted in the vault."
11407 msgid "Ansible Vault uses an editor to create or modify encrypted files. See :ref:`vault_securing_e…
11411 msgid "Advantages and disadvantages of encrypting files"
11415 msgid "File-level encryption is easy to use. Password rotation for encrypted files is straightforwa…
11419 msgid "Creating encrypted files"
11423 msgid "To create a new encrypted data file called 'foo.yml' with the 'test' vault password from 'mu…
11427 msgid "The tool launches an editor (whatever editor you have defined with $EDITOR, default editor i…
11431 msgid "To create a new encrypted data file with the vault ID 'my_new_password' assigned to it and b…
11435 msgid "Again, add content to the file in the editor and save. Be sure to store the new password you…
11439 msgid "Encrypting existing files"
11443 msgid "To encrypt an existing file, use the :ref:`ansible-vault encrypt <ansible_vault_encrypt>` co…
11447 msgid "To encrypt existing files with the 'project' ID and be prompted for the password:"
11451 msgid "Viewing encrypted files"
11455 msgid "To view the contents of an encrypted file without editing it, you can use the :ref:`ansible-…
11459 msgid "Editing encrypted files"
11463 msgid "To edit an encrypted file in place, use the :ref:`ansible-vault edit <ansible_vault_edit>` c…
11467 msgid "To edit a file encrypted with the ``vault2`` password file and assigned the vault ID ``pass2…
11471 msgid "Changing the password and/or vault ID on encrypted files"
11475 msgid "To change the password on an encrypted file or files, use the :ref:`rekey <ansible_vault_rek…
11479 msgid "This command can rekey multiple data files at once and will ask for the original password an…
11483 msgid "Decrypting encrypted files"
11487 msgid "If you have an encrypted file that you no longer want to keep encrypted, you can permanently…
11491 msgid "Steps to secure your editor"
11495 msgid "Ansible Vault relies on your configured editor, which can be a source of disclosures. Most e…
11499 msgid "vim"
11503 msgid "You can set the following ``vim`` options in command mode to avoid cases of disclosure. Ther…
11507 msgid "Disable swapfiles that act like an autosave in case of crash or interruption."
11511 msgid "Disable creation of backup files."
11515 msgid "Disable the viminfo file from copying data from your current session."
11519 msgid "Disable copying to the system clipboard."
11523 msgid "You can optionally add these settings in ``.vimrc`` for all files, or just specific paths or…
11527 msgid "Emacs"
11531 msgid "You can set the following Emacs options to avoid cases of disclosure. There may be more sett…
11535 msgid "Do not copy data to the system clipboard."
11539 msgid "Disable autosave files."
11543 msgid "Using encrypted variables and files"
11547 msgid "When you run a task or playbook that uses encrypted variables or files, you must provide the…
11551 msgid "Passing a single password"
11555 msgid "If all the encrypted variables and files your task or playbook needs use a single password, …
11559 msgid "To prompt for the password:"
11563 msgid "To retrieve the password from the :file:`/path/to/my/vault-password-file` file:"
11567 msgid "To get the password from the vault password client script :file:`my-vault-password-client.py…
11571 msgid "Passing vault IDs"
11575 msgid "You can also use the :option:`--vault-id <ansible-playbook --vault-id>` option to pass a sin…
11579 msgid "To prompt for the password for the 'dev' vault ID:"
11583 msgid "To retrieve the password for the 'dev' vault ID from the :file:`dev-password` file:"
11587 msgid "To get the password for the 'dev' vault ID from the vault password client script :file:`my-v…
11591 msgid "Passing multiple vault passwords"
11595 msgid "If your task or playbook requires multiple encrypted variables or files that you encrypted w…
11599 msgid "By default the vault ID labels (dev, prod and so on) are only hints. Ansible attempts to dec…
11603 msgid "Where the encrypted data has no label, or the label does not match any of the provided label…
11607 msgid "Using ``--vault-id`` without a vault ID"
11611 msgid "The :option:`--vault-id <ansible-playbook --vault-id>` option can also be used without speci…
11615 msgid "For example, to use a password file :file:`dev-password`:"
11619 msgid "To get the password from an executable script :file:`my-vault-password-client.py`:"
11623 msgid "Configuring defaults for using encrypted content"
11627 msgid "Setting a default vault ID"
11631 msgid "If you use one vault ID more frequently than any other, you can set the config option :ref:`…
11635 msgid "Setting a default password source"
11639 msgid "If you use one vault password file more frequently than any other, you can set the :ref:`DEF…
11643 msgid "When are encrypted files made visible?"
11647 msgid "In general, content you encrypt with Ansible Vault remains encrypted after execution. Howeve…
11651 msgid "Speeding up Ansible Vault"
11655 msgid "If you have many encrypted files, decrypting them at startup may cause a perceptible delay. …
11659 msgid "Format of files encrypted with Ansible Vault"
11663 msgid "Ansible Vault creates UTF-8 encoded txt files. The file format includes a newline terminated…
11667 msgid "or::"
11671 msgid "The header contains up to four elements, separated by semi-colons (``;``)."
11675 msgid "The format ID (``$ANSIBLE_VAULT``). Currently ``$ANSIBLE_VAULT`` is the only valid format ID…
11679 msgid "The vault format version (``1.X``). All supported versions of Ansible will currently default…
11683 msgid "The cipher algorithm used to encrypt the data (``AES256``). Currently ``AES256`` is the only…
11687 msgid "The vault ID label used to encrypt the data (optional, ``vault-id-label``) For example, if y…
11691 msgid "Note: In the future, the header could change. Fields after the format ID and format version …
11695 msgid "The rest of the content of the file is the 'vaulttext'. The vaulttext is a text armored vers…
11699 msgid "Ansible Vault payload format 1.1 - 1.2"
11703 msgid "The vaulttext is a concatenation of the ciphertext and a SHA256 digest with the result 'hexl…
11707 msgid "'hexlify' refers to the ``hexlify()`` method of the Python Standard Library's `binascii <htt…
11711 msgid "hexlify()'ed result of:"
11715 msgid "hexlify()'ed string of the salt, followed by a newline (``0x0a``)"
11719 msgid "hexlify()'ed string of the crypted HMAC, followed by a newline. The HMAC is:"
11723 msgid "a `RFC2104 <https://www.ietf.org/rfc/rfc2104.txt>`_ style HMAC"
11727 msgid "inputs are:"
11731 msgid "The AES256 encrypted ciphertext"
11735 msgid "A PBKDF2 key. This key, the cipher key, and the cipher IV are generated from:"
11739 msgid "the salt, in bytes"
11743 msgid "10000 iterations"
11747 msgid "SHA256() algorithm"
11751 msgid "the first 32 bytes are the cipher key"
11755 msgid "the second 32 bytes are the HMAC key"
11759 msgid "remaining 16 bytes are the cipher IV"
11763 msgid "hexlify()'ed string of the ciphertext. The ciphertext is:"
11767 msgid "AES256 encrypted data. The data is encrypted using:"
11771 msgid "AES-CTR stream cipher"
11775 msgid "cipher key"
11779 msgid "IV"
11783 msgid "a 128 bit counter block seeded from an integer IV"
11787 msgid "the plaintext"
11791 msgid "the original plaintext"
11795 msgid "padding up to the AES256 blocksize. (The data used for padding is based on `RFC5652 <https:/…
11799 msgid "Windows Guides"
11803 msgid "The following sections provide information on managing Windows hosts with Ansible."
11807 msgid "Because Windows is a non-POSIX-compliant operating system, there are differences between how…
11811 msgid "Desired State Configuration"
11815 msgid "What is Desired State Configuration?"
11819 msgid "Desired State Configuration, or DSC, is a tool built into PowerShell that can be used to def…
11823 msgid "More details on DSC can be viewed at `DSC Overview <https://docs.microsoft.com/en-us/powersh…
11828 msgid "Host Requirements"
11832 msgid "To use the ``win_dsc`` module, a Windows host must have PowerShell v5.0 or newer installed. …
11836 msgid "Once the PowerShell requirements have been met, using DSC is as simple as creating a task wi…
11840 msgid "Why Use DSC?"
11844 msgid "DSC and Ansible modules have a common goal which is to define and ensure the state of a reso…
11848 msgid "Reasons for using an Ansible module over a DSC resource:"
11852 msgid "The host does not support PowerShell v5.0, or it cannot easily be upgraded"
11856 msgid "The DSC resource does not offer a feature present in an Ansible module. For example win_rege…
11860 msgid "DSC resources have limited check mode support, while some Ansible modules have better checks"
11864 msgid "DSC resources do not support diff mode, while some Ansible modules do"
11868 msgid "Custom resources require further installation steps to be run on the host beforehand, while …
11872 msgid "There are bugs in a DSC resource where an Ansible module works"
11876 msgid "Reasons for using a DSC resource over an Ansible module:"
11880 msgid "The Ansible module does not support a feature present in a DSC resource"
11884 msgid "There is no Ansible module available"
11888 msgid "There are bugs in an existing Ansible module"
11892 msgid "In the end, it doesn't matter whether the task is performed with DSC or an Ansible module; w…
11896 msgid "How to Use DSC?"
11900 msgid "The ``win_dsc`` module takes in a free-form of options so that it changes according to the r…
11904 msgid "Using the `Registry <https://docs.microsoft.com/en-us/powershell/scripting/dsc/reference/res…
11908 msgid "When defining the task, ``resource_name`` must be set to the DSC resource being used - in th…
11912 msgid "This is what the Ansible task version of the above DSC Registry resource would look like:"
11916 msgid "Starting in Ansible 2.8, the ``win_dsc`` module automatically validates the input options fr…
11920 msgid "The ``invocation.module_args`` key shows the actual values that were set as well as other po…
11924 msgid "Property Types"
11928 msgid "Each DSC resource property has a type that is associated with it. Ansible will try to conver…
11932 msgid "PSCredential"
11936 msgid "A ``[PSCredential]`` object is used to store credentials in a secure way, but Ansible has no…
11940 msgid "On versions of Ansible older than 2.8, you should set ``no_log: yes`` on the task definition…
11944 msgid "A ``[PSCredential]`` is defined with ``EmbeddedInstance(\"MSFT_Credential\")`` in a DSC reso…
11948 msgid "CimInstance Type"
11952 msgid "A ``[CimInstance]`` object is used by DSC to store a dictionary object based on a custom cla…
11956 msgid "In the above example, the CIM instance is a representation of the class `MSFT_xWebAuthentica…
11960 msgid "HashTable Type"
11964 msgid "A ``[HashTable]`` object is also a dictionary but does not have a strict set of keys that ca…
11968 msgid "Arrays"
11972 msgid "Simple type arrays like ``[string[]]`` or ``[UInt32[]]`` are defined as a list or as a comma…
11976 msgid "Complex type arrays like ``[CimInstance[]]`` (array of dicts), can be defined like this exam…
11980 msgid "The above example, is an array with two values of the class `MSFT_xWebBindingInformation <ht…
11984 msgid "DateTime"
11988 msgid "A ``[DateTime]`` object is a DateTime string representing the date and time in the `ISO 8601…
11992 msgid "All the values above are equal to a UTC date time of February 22nd 2019 at 1:57pm with 31 se…
11996 msgid "Run As Another User"
12000 msgid "By default, DSC runs each resource as the SYSTEM account and not the account that Ansible us…
12004 msgid "Using the Registry resource type as an example, this is how to define a task to access the `…
12008 msgid "Custom DSC Resources"
12012 msgid "DSC resources are not limited to the built-in options from Microsoft. Custom modules can be …
12016 msgid "Finding Custom DSC Resources"
12020 msgid "You can use the `PSGallery <https://www.powershellgallery.com/>`_ to find custom resources, …
12024 msgid "The ``Find-DscResource`` cmdlet can also be used to find custom resources. For example:"
12028 msgid "DSC resources developed by Microsoft that start with ``x``, means the resource is experiment…
12032 msgid "Installing a Custom Resource"
12036 msgid "There are three ways that a DSC resource can be installed on a host:"
12040 msgid "Manually with the ``Install-Module`` cmdlet"
12044 msgid "Using the ``win_psmodule`` Ansible module"
12048 msgid "Saving the module manually and copying it another host"
12052 msgid "This is an example of installing the ``xWebAdministration`` resources using ``win_psmodule``…
12056 msgid "Once installed, the win_dsc module will be able to use the resource by referencing it with t…
12060 msgid "The first two methods above only work when the host has access to the internet. When a host …
12064 msgid "This will create a folder called ``xWebAdministration`` in ``C:\\temp`` which can be copied …
12068 msgid "Examples"
12072 msgid "Extract a zip file"
12076 msgid "Create a directory"
12080 msgid "Interact with Azure"
12084 msgid "Setup IIS Website"
12091 msgid ":ref:`List of Windows Modules <windows_modules>`"
12098 msgid "Windows specific module list, all implemented in PowerShell"
12102 msgid "Windows Frequently Asked Questions"
12106 msgid "Here are some commonly asked questions in regards to Ansible and Windows and their answers."
12110 msgid "This document covers questions about managing Microsoft Windows servers with Ansible. For qu…
12114 msgid "Does Ansible work with Windows XP or Server 2003?"
12118 msgid "Ansible does not work with Windows XP or Server 2003 hosts. Ansible does work with these Win…
12122 msgid "Windows Server 2008 :sup:`1`"
12126 msgid "Windows Server 2008 R2 :sup:`1`"
12130 msgid "Windows Server 2012"
12134 msgid "Windows Server 2012 R2"
12138 msgid "Windows Server 2016"
12142 msgid "Windows Server 2019"
12146 msgid "Windows 7 :sup:`1`"
12150 msgid "Windows 8.1"
12154 msgid "Windows 10"
12158 msgid "1 - See the :ref:`Server 2008 FAQ <windows_faq_server2008>` entry for more details."
12162 msgid "Ansible also has minimum PowerShell version requirements - please see :ref:`windows_setup` f…
12166 msgid "Are Server 2008, 2008 R2 and Windows 7 supported?"
12170 msgid "Microsoft ended Extended Support for these versions of Windows on January 14th, 2020, and An…
12174 msgid "Can I manage Windows Nano Server with Ansible?"
12178 msgid "Ansible does not currently work with Windows Nano Server, since it does not have access to t…
12182 msgid "Can Ansible run on Windows?"
12186 msgid "No, Ansible can only manage Windows hosts. Ansible cannot run on a Windows host natively, th…
12190 msgid "The Windows Subsystem for Linux is not supported by Ansible and should not be used for produ…
12194 msgid "To install Ansible on WSL, the following commands can be run in the bash terminal:"
12198 msgid "To run Ansible from source instead of a release on the WSL, simply uninstall the pip install…
12202 msgid "If you encounter timeout errors when running Ansible on the WSL, this may be due to an issue…
12206 msgid "Another option is to use WSL 2 if running Windows 10 later than build 2004."
12210 msgid "Can I use SSH keys to authenticate to Windows hosts?"
12214 msgid "You cannot use SSH keys with the WinRM or PSRP connection plugins. These connection plugins …
12218 msgid "The way X509 certificates are generated and mapped to a user is different from the SSH imple…
12222 msgid "Ansible 2.8 has added an experimental option to use the SSH connection plugin, which uses SS…
12226 msgid "Why can I run a command locally that does not work under Ansible?"
12230 msgid "Ansible executes commands through WinRM. These processes are different from running a comman…
12234 msgid "Unless using an authentication option like CredSSP or Kerberos with credential delegation, t…
12238 msgid "All processes run under WinRM are in a non-interactive session. Applications that require an…
12242 msgid "When running through WinRM, Windows restricts access to internal Windows APIs like the Windo…
12246 msgid "Some ways to bypass these restrictions are to:"
12250 msgid "Use ``become``, which runs a command as it would when run locally. This will bypass most Win…
12254 msgid "Use a scheduled task, which can be created with ``win_scheduled_task``. Like ``become``, it …
12258 msgid "Use ``win_psexec`` to run a command on the host. PSExec does not use WinRM and so will bypas…
12262 msgid "To access network resources without any of these workarounds, you can use CredSSP or Kerbero…
12266 msgid "See :ref:`become` more info on how to use become. The limitations section at :ref:`windows_w…
12270 msgid "This program won't install on Windows with Ansible"
12274 msgid "See :ref:`this question <windows_faq_winrm>` for more information about WinRM limitations."
12278 msgid "What Windows modules are available?"
12282 msgid "Most of the Ansible modules in Ansible Core are written for a combination of Linux/Unix mach…
12286 msgid "Because of this, there are dedicated Windows modules that are written in PowerShell and are …
12290 msgid "In addition, the following Ansible Core modules/action-plugins work with Windows:"
12294 msgid "add_host"
12298 msgid "assert"
12302 msgid "async_status"
12306 msgid "debug"
12310 msgid "fail"
12314 msgid "fetch"
12318 msgid "group_by"
12322 msgid "include"
12326 msgid "include_role"
12330 msgid "meta"
12334 msgid "pause"
12338 msgid "raw"
12342 msgid "script"
12346 msgid "set_fact"
12350 msgid "set_stats"
12354 msgid "setup"
12358 msgid "slurp"
12362 msgid "template (also: win_template)"
12366 msgid "wait_for_connection"
12370 msgid "Can I run Python modules on Windows hosts?"
12374 msgid "No, the WinRM connection protocol is set to use PowerShell modules, so Python modules will n…
12378 msgid "Can I connect to Windows hosts over SSH?"
12382 msgid "Ansible 2.8 has added an experimental option to use the SSH connection plugin to manage Wind…
12386 msgid "To use SSH as the connection to a Windows host, set the following variables in the inventory…
12390 msgid "The value for ``ansible_shell_type`` should either be ``cmd`` or ``powershell``. Use ``cmd``…
12394 msgid "Why is connecting to a Windows host via SSH failing?"
12398 msgid "Unless you are using ``Win32-OpenSSH`` as described above, you must connect to Windows hosts…
12402 msgid "Make sure ``ansible_connection: winrm`` is set in the inventory for the Windows host(s)."
12406 msgid "Why are my credentials being rejected?"
12410 msgid "This can be due to a myriad of reasons unrelated to incorrect credentials."
12414 msgid "See HTTP 401/Credentials Rejected at :ref:`windows_setup` for a more detailed guide of this …
12418 msgid "Why am I getting an error SSL CERTIFICATE_VERIFY_FAILED?"
12422 msgid "When the Ansible controller is running on Python 2.7.9+ or an older version of Python that h…
12426 msgid "To ignore certificate validation, add ``ansible_winrm_server_cert_validation: ignore`` to in…
12430 msgid ":ref:`windows`"
12434 msgid "The Windows documentation index"
12438 msgid "Windows performance"
12442 msgid "This document offers some performance optimizations you might like to apply to your Windows …
12446 msgid "Optimise PowerShell performance to reduce Ansible task overhead"
12450 msgid "To speed up the startup of PowerShell by around 10x, run the following PowerShell snippet in…
12454 msgid "If native images have already been created by the ngen task or service, you will observe no …
12458 msgid "PowerShell is used by every Windows Ansible module. This optimisation reduces the time Power…
12462 msgid "This snippet uses `the native image generator, ngen <https://docs.microsoft.com/en-us/dotnet…
12466 msgid "Fix high-CPU-on-boot for VMs/cloud instances"
12470 msgid "If you are creating golden images to spawn instances from, you can avoid a disruptive high C…
12474 msgid "Place the following near the end of your playbook, bearing in mind the factors that can caus…
12478 msgid "Setting up a Windows Host"
12482 msgid "This document discusses the setup that is required before Ansible can communicate with a Mic…
12486 msgid "For Ansible to communicate to a Windows host and use Windows modules, the Windows host must …
12490 msgid "Ansible can generally manage Windows versions under current and extended support from Micros…
12494 msgid "Ansible requires PowerShell 3.0 or newer and at least .NET 4.0 to be installed on the Window…
12498 msgid "A WinRM listener should be created and activated. More details for this can be found below."
12502 msgid "While these are the base requirements for Ansible connectivity, some Ansible modules have ad…
12506 msgid "Upgrading PowerShell and .NET Framework"
12510 msgid "Ansible requires PowerShell version 3.0 and .NET Framework 4.0 or newer to function on older…
12514 msgid "This is an example of how to run this script from PowerShell:"
12518 msgid "Once completed, you will need to remove auto logon and set the execution policy back to the …
12522 msgid "The script works by checking to see what programs need to be installed (such as .NET Framewo…
12526 msgid "If running on Server 2008, then SP2 must be installed. If running on Server 2008 R2 or Windo…
12530 msgid "Windows Server 2008 can only install PowerShell 3.0; specifying a newer version will result …
12534 msgid "The ``username`` and ``password`` parameters are stored in plain text in the registry. Make …
12538 msgid "WinRM Memory Hotfix"
12542 msgid "When running on PowerShell v3.0, there is a bug with the WinRM service that limits the amoun…
12546 msgid "The following PowerShell command will install the hotfix:"
12550 msgid "For more details, please refer to the `Hotfix document <https://support.microsoft.com/en-us/…
12554 msgid "WinRM Setup"
12558 msgid "Once Powershell has been upgraded to at least version 3.0, the final step is for the WinRM s…
12562 msgid "Details about each component can be read below, but the script `ConfigureRemotingForAnsible.…
12566 msgid "To use this script, run the following in PowerShell:"
12570 msgid "There are different switches and parameters (like ``-EnableCredSSP`` and ``-ForceNewSSLCert`…
12574 msgid "The ConfigureRemotingForAnsible.ps1 script is intended for training and development purposes…
12578 msgid "WinRM Listener"
12582 msgid "The WinRM services listens for requests on one or more ports. Each of these ports must have …
12586 msgid "To view the current listeners that are running on the WinRM service, run the following comma…
12591 msgid "This will output something like::"
12595 msgid "In the example above there are two listeners activated; one is listening on port 5985 over H…
12599 msgid "``Transport``: Whether the listener is run over HTTP or HTTPS, it is recommended to use a li…
12603 msgid "``Port``: The port the listener runs on, by default it is ``5985`` for HTTP and ``5986`` for…
12607 msgid "``URLPrefix``: The URL prefix to listen on, by default it is ``wsman``. If this is changed, …
12611 msgid "``CertificateThumbprint``: If running over an HTTPS listener, this is the thumbprint of the …
12615 msgid "Setup WinRM Listener"
12619 msgid "There are three ways to set up a WinRM listener:"
12623 msgid "Using ``winrm quickconfig`` for HTTP or ``winrm quickconfig -transport:https`` for HTTPS. Th…
12627 msgid "Using Group Policy Objects. This is the best way to create a listener when the host is a mem…
12631 msgid "Using PowerShell to create the listener with a specific configuration. This can be done by r…
12635 msgid "To see the other options with this PowerShell cmdlet, see `New-WSManInstance <https://docs.m…
12639 msgid "When creating an HTTPS listener, an existing certificate needs to be created and stored in t…
12643 msgid "Delete WinRM Listener"
12647 msgid "To remove a WinRM listener::"
12651 msgid "The ``Keys`` object is an array of strings, so it can contain different values. By default i…
12655 msgid "WinRM Service Options"
12659 msgid "There are a number of options that can be set to control the behavior of the WinRM service c…
12663 msgid "To get an output of the current service configuration options, run the following command:"
12667 msgid "While many of these options should rarely be changed, a few can easily impact the operations…
12671 msgid "``Service\\AllowUnencrypted``: This option defines whether WinRM will allow traffic that is …
12675 msgid "``Service\\Auth\\*``: These flags define what authentication options are allowed with the Wi…
12679 msgid "``Service\\Auth\\CbtHardeningLevel``: Specifies whether channel binding tokens are not verif…
12683 msgid "``Service\\CertificateThumbprint``: This is the thumbprint of the certificate used to encryp…
12687 msgid "``Winrs\\MaxShellRunTime``: This is the maximum time, in milliseconds, that a remote command…
12691 msgid "``Winrs\\MaxMemoryPerShellMB``: This is the maximum amount of memory allocated per shell, in…
12695 msgid "To modify a setting under the ``Service`` key in PowerShell::"
12699 msgid "To modify a setting under the ``Winrs`` key in PowerShell::"
12703 msgid "If running in a domain environment, some of these options are set by GPO and cannot be chang…
12707 msgid "Common WinRM Issues"
12711 msgid "Because WinRM has a wide range of configuration options, it can be difficult to setup and co…
12715 msgid "One easy way to determine whether a problem is a host issue is to run the following command …
12719 msgid "If this fails, the issue is probably related to the WinRM setup. If it works, the issue may …
12723 msgid "HTTP 401/Credentials Rejected"
12727 msgid "A HTTP 401 error indicates the authentication process failed during the initial connection. …
12731 msgid "Verify that the credentials are correct and set properly in your inventory with ``ansible_us…
12735 msgid "Ensure that the user is a member of the local Administrators group or has been explicitly gr…
12739 msgid "Make sure that the authentication option set by ``ansible_winrm_transport`` is enabled under…
12743 msgid "If running over HTTP and not HTTPS, use ``ntlm``, ``kerberos`` or ``credssp`` with ``ansible…
12747 msgid "Ensure the downstream packages ``pywinrm``, ``requests-ntlm``, ``requests-kerberos``, and/or…
12751 msgid "If using Kerberos authentication, ensure that ``Service\\Auth\\CbtHardeningLevel`` is not se…
12755 msgid "When using Basic or Certificate authentication, make sure that the user is a local account a…
12759 msgid "HTTP 500 Error"
12763 msgid "These indicate an error has occurred with the WinRM service. Some things to check for includ…
12767 msgid "Verify that the number of current open shells has not exceeded either ``WinRsMaxShellsPerUse…
12771 msgid "Timeout Errors"
12775 msgid "These usually indicate an error with the network connection where Ansible is unable to reach…
12779 msgid "Make sure the firewall is not set to block the configured WinRM listener ports"
12783 msgid "Ensure that a WinRM listener is enabled on the port and path set by the host vars"
12787 msgid "Ensure that the ``winrm`` service is running on the Windows host and configured for automati…
12791 msgid "Connection Refused Errors"
12795 msgid "These usually indicate an error when trying to communicate with the WinRM service on the hos…
12799 msgid "Ensure that the WinRM service is up and running on the host. Use ``(Get-Service -Name winrm)…
12803 msgid "Check that the host firewall is allowing traffic over the WinRM port. By default this is ``5…
12807 msgid "Sometimes an installer may restart the WinRM or HTTP service and cause this error. The best …
12811 msgid "Failure to Load Builtin Modules"
12815 msgid "If powershell fails with an error message similar to ``The 'Out-String' command was found in…
12819 msgid "Remove the UNC path from the ``PSModulePath`` environment variable, or"
12823 msgid "Use an authentication option that supports credential delegation like ``credssp`` or ``kerbe…
12827 msgid "See `KB4076842 <https://support.microsoft.com/en-us/help/4076842>`_ for more information on …
12831 msgid "Windows SSH Setup"
12835 msgid "Ansible 2.8 has added an experimental SSH connection for Windows managed nodes."
12839 msgid "Use this feature at your own risk! Using SSH with Windows is experimental, the implementatio…
12843 msgid "Installing Win32-OpenSSH"
12847 msgid "The first step to using SSH with Windows is to install the `Win32-OpenSSH <https://github.co…
12851 msgid "Manually install the service, following the `install instructions <https://github.com/PowerS…
12855 msgid "Install the `openssh <https://chocolatey.org/packages/openssh>`_ package using Chocolatey::"
12859 msgid "Use ``win_chocolatey`` to install the service::"
12863 msgid "Use an existing Ansible Galaxy role like `jborean93.win_openssh <https://galaxy.ansible.com/…
12867 msgid "``Win32-OpenSSH`` is still a beta product and is constantly being updated to include new fea…
12871 msgid "Configuring the Win32-OpenSSH shell"
12875 msgid "By default ``Win32-OpenSSH`` will use ``cmd.exe`` as a shell. To configure a different shell…
12879 msgid "Win32-OpenSSH Authentication"
12883 msgid "Win32-OpenSSH authentication with Windows is similar to SSH authentication on Unix/Linux hos…
12887 msgid "When using SSH key authentication with Ansible, the remote session won't have access to the …
12891 msgid "Use plaintext password auth by setting ``ansible_password``"
12895 msgid "Use ``become`` on the task with the credentials of the user that needs access to the remote …
12899 msgid "Configuring Ansible for SSH on Windows"
12903 msgid "To configure Ansible to use SSH for Windows hosts, you must set two connection variables:"
12907 msgid "set ``ansible_connection`` to ``ssh``"
12911 msgid "set ``ansible_shell_type`` to ``cmd`` or ``powershell``"
12915 msgid "The ``ansible_shell_type`` variable should reflect the ``DefaultShell`` configured on the Wi…
12919 msgid "Known issues with SSH on Windows"
12923 msgid "Using SSH with Windows is experimental, and we expect to uncover more issues. Here are the k…
12927 msgid "Win32-OpenSSH versions older than ``v7.9.0.0p1-Beta`` do not work when ``powershell`` is the…
12931 msgid "While SCP should work, SFTP is the recommended SSH file transfer mechanism to use when copyi…
12935 msgid "Using Ansible and Windows"
12939 msgid "When using Ansible to manage Windows, many of the syntax and rules that apply for Unix/Linux…
12943 msgid "Use Cases"
12947 msgid "Ansible can be used to orchestrate a multitude of tasks on Windows servers. Below are some e…
12951 msgid "Installing Software"
12955 msgid "There are three main ways that Ansible can be used to install software:"
12959 msgid "Using the ``win_chocolatey`` module. This sources the program data from the default public `…
12963 msgid "Using the ``win_package`` module. This installs software using an MSI or .exe installer from…
12967 msgid "Using the ``win_command`` or ``win_shell`` module to run an installer manually."
12971 msgid "The ``win_chocolatey`` module is recommended since it has the most complete logic for checki…
12975 msgid "Below are some examples of using all three options to install 7-Zip:"
12979 msgid "Some installers like Microsoft Office or SQL Server require credential delegation or access …
12983 msgid "Many installers do not properly pass back error information over WinRM. In these cases, if t…
12987 msgid "Some installers restart the WinRM or HTTP services, or cause them to become temporarily unav…
12991 msgid "Installing Updates"
12995 msgid "The ``win_updates`` and ``win_hotfix`` modules can be used to install updates or hotfixes on…
12999 msgid "The ``win_hotfix`` module has a requirement that the DISM PowerShell cmdlets are present. Th…
13003 msgid "The following example shows how ``win_updates`` can be used:"
13007 msgid "The following example show how ``win_hotfix`` can be used to install a single update or hotf…
13011 msgid "Set Up Users and Groups"
13015 msgid "Ansible can be used to create Windows users and groups both locally and on a domain."
13019 msgid "Local"
13023 msgid "The modules ``win_user``, ``win_group`` and ``win_group_membership`` manage Windows users, g…
13027 msgid "The following is an example of creating local accounts and groups that can access a folder o…
13031 msgid "Domain"
13035 msgid "The modules ``win_domain_user`` and ``win_domain_group`` manages users and groups in a domai…
13039 msgid "Running Commands"
13043 msgid "In cases where there is no appropriate module available for a task, a command or script can …
13047 msgid "The ``raw`` module simply executes a Powershell command remotely. Since ``raw`` has none of …
13051 msgid "The ``script`` module executes a script from the Ansible controller on one or more Windows h…
13055 msgid "The ``win_command`` module is used to execute a command which is either an executable or bat…
13059 msgid "Choosing Command or Shell"
13063 msgid "The ``win_shell`` and ``win_command`` modules can both be used to execute a command or comma…
13067 msgid "The ``win_command`` module simply runs a process outside of a shell. It can still run a shel…
13071 msgid "Here are some examples of using ``win_command`` and ``win_shell``:"
13075 msgid "Some commands like ``mkdir``, ``del``, and ``copy`` only exist in the CMD shell. To run them…
13079 msgid "Argument Rules"
13083 msgid "When running a command through ``win_command``, the standard Windows argument rules apply:"
13087 msgid "Each argument is delimited by a white space, which can either be a space or a tab."
13091 msgid "An argument can be surrounded by double quotes ``\"``. Anything inside these quotes is inter…
13095 msgid "A double quote preceded by a backslash ``\\`` is interpreted as just a double quote ``\"`` a…
13099 msgid "Backslashes are interpreted literally unless it immediately precedes double quotes; for exam…
13103 msgid "If an even number of backslashes is followed by a double quote, one backslash is used in the…
13107 msgid "If an odd number of backslashes is followed by a double quote, one backslash is used in the …
13111 msgid "With those rules in mind, here are some examples of quoting:"
13115 msgid "For more information, see `escaping arguments <https://msdn.microsoft.com/en-us/library/17w5…
13119 msgid "Creating and Running a Scheduled Task"
13123 msgid "WinRM has some restrictions in place that cause errors when running certain commands. One wa…
13127 msgid "Ansible version 2.5 added modules that make it easier to work with scheduled tasks in Window…
13131 msgid "The modules used in the above example were updated/added in Ansible version 2.5."
13135 msgid "Path Formatting for Windows"
13139 msgid "Windows differs from a traditional POSIX operating system in many ways. One of the major cha…
13143 msgid "Ansible allows two different styles of syntax; each deals with path separators for Windows d…
13147 msgid "YAML Style"
13151 msgid "When using the YAML syntax for tasks, the rules are well-defined by the YAML standard:"
13155 msgid "When using a normal string (without quotes), YAML will not consider the backslash an escape …
13159 msgid "When using single quotes ``'``, YAML will not consider the backslash an escape character."
13163 msgid "When using double quotes ``\"``, the backslash is considered an escape character and needs t…
13167 msgid "You should only quote strings when it is absolutely necessary or required by YAML, and then …
13171 msgid "The YAML specification considers the following `escape sequences <https://yaml.org/spec/curr…
13175 msgid "``\\0``, ``\\\\``, ``\\\"``, ``\\_``, ``\\a``, ``\\b``, ``\\e``, ``\\f``, ``\\n``, ``\\r``, …
13180 msgid "``<TAB>``, ``<SPACE>``, ``<NBSP>``, ``<LNSP>``, ``<PSP>`` -- Special characters"
13185 msgid "``\\x..`` -- 2-digit hex escape"
13190 msgid "``\\u....`` -- 4-digit hex escape"
13195 msgid "``\\U........`` -- 8-digit hex escape"
13199 msgid "Here are some examples on how to write Windows paths::"
13203 msgid "This is an example which will fail:"
13207 msgid "This example shows the use of single quotes when they are required::"
13211 msgid "Legacy key=value Style"
13215 msgid "The legacy ``key=value`` syntax is used on the command line for ad hoc commands, or inside p…
13219 msgid "The Ansible key=value parser parse_kv() considers the following escape sequences:"
13223 msgid "``\\``, ``'``, ``\"``, ``\\a``, ``\\b``, ``\\f``, ``\\n``, ``\\r``, ``\\t`` and ``\\v`` -- S…
13228 msgid "``\\N{...}`` -- Unicode character by name"
13232 msgid "This means that the backslash is an escape character for some sequences, and it is usually s…
13236 msgid "Here are some examples of using Windows paths with the key=value style:"
13240 msgid "The failing examples don't fail outright but will substitute ``\\t`` with the ``<TAB>`` char…
13245 msgid "Limitations"
13249 msgid "Some things you cannot do with Ansible and Windows are:"
13253 msgid "Upgrade PowerShell"
13257 msgid "Interact with the WinRM listeners"
13261 msgid "Because WinRM is reliant on the services being online and running during normal operations, …
13265 msgid "Developing Windows Modules"
13269 msgid "Because Ansible modules for Windows are written in PowerShell, the development guides for Wi…
13273 msgid "Windows Remote Management"
13277 msgid "Unlike Linux/Unix hosts, which use SSH by default, Windows hosts are configured with WinRM. …
13281 msgid "What is WinRM?"
13285 msgid "WinRM is a management protocol used by Windows to remotely communicate with another server. …
13289 msgid "Ansible uses the `pywinrm <https://github.com/diyan/pywinrm>`_ package to communicate with W…
13293 msgid "on distributions with multiple python versions, use pip2 or pip2.x, where x matches the pyth…
13297 msgid "Using the ``winrm`` or ``psrp`` connection plugins in Ansible on MacOS in the latest release…
13301 msgid "Authentication Options"
13305 msgid "When connecting to a Windows host, there are several different options that can be used when…
13309 msgid "The following matrix is a high level overview of the options:"
13313 msgid "Option"
13317 msgid "Local Accounts"
13321 msgid "Active Directory Accounts"
13325 msgid "Credential Delegation"
13329 msgid "HTTP Encryption"
13334 msgid "Basic"
13342 msgid "Yes"
13349 msgid "No"
13354 msgid "Certificate"
13359 msgid "Kerberos"
13364 msgid "NTLM"
13369 msgid "CredSSP"
13373 msgid "Basic authentication is one of the simplest authentication options to use, but is also the m…
13377 msgid "The following example shows host vars configured for basic authentication:"
13381 msgid "Basic authentication is not enabled by default on a Windows host but can be enabled by runni…
13385 msgid "Certificate authentication uses certificates as keys similar to SSH key pairs, but the file …
13389 msgid "The following example shows host vars configured for certificate authentication:"
13393 msgid "Certificate authentication is not enabled by default on a Windows host but can be enabled by…
13397 msgid "Encrypted private keys cannot be used as the urllib3 library that is used by Ansible for Win…
13401 msgid "Generate a Certificate"
13405 msgid "A certificate must be generated before it can be mapped to a local user. This can be done us…
13409 msgid "OpenSSL"
13413 msgid "PowerShell, using the ``New-SelfSignedCertificate`` cmdlet"
13417 msgid "Active Directory Certificate Services"
13421 msgid "Active Directory Certificate Services is beyond of scope in this documentation but may be th…
13425 msgid "Using the PowerShell cmdlet ``New-SelfSignedCertificate`` to generate a certificate for auth…
13429 msgid "To generate a certificate with ``OpenSSL``:"
13433 msgid "To generate a certificate with ``New-SelfSignedCertificate``:"
13437 msgid "To convert the PFX file to a private key that pywinrm can use, run the following command wit…
13441 msgid "Import a Certificate to the Certificate Store"
13445 msgid "Once a certificate has been generated, the issuing certificate needs to be imported into the…
13449 msgid "Following example shows how to import the issuing certificate:"
13453 msgid "If using ADCS to generate the certificate, then the issuing certificate will already be impo…
13457 msgid "The code to import the client certificate public key is:"
13461 msgid "Mapping a Certificate to an Account"
13465 msgid "Once the certificate has been imported, map it to the local user account::"
13469 msgid "Once this is complete, the hostvar ``ansible_winrm_cert_pem`` should be set to the path of t…
13473 msgid "NTLM is an older authentication mechanism used by Microsoft that can support both local and …
13477 msgid "NTLM is the easiest authentication protocol to use and is more secure than ``Basic`` authent…
13481 msgid "Kerberos has several advantages over using NTLM:"
13485 msgid "NTLM is an older protocol and does not support newer encryption protocols."
13489 msgid "NTLM is slower to authenticate because it requires more round trips to the host in the authe…
13493 msgid "Unlike Kerberos, NTLM does not allow credential delegation."
13497 msgid "This example shows host variables configured to use NTLM authentication:"
13501 msgid "Kerberos is the recommended authentication option to use when running in a domain environmen…
13505 msgid "Kerberos requires some additional setup work on the Ansible host before it can be used prope…
13509 msgid "The following example shows host vars configured for Kerberos authentication:"
13513 msgid "As of Ansible version 2.3, the Kerberos ticket will be created based on ``ansible_user`` and…
13517 msgid "There are some extra host variables that can be set::"
13521 msgid "Installing the Kerberos Library"
13525 msgid "Some system dependencies that must be installed prior to using Kerberos. The script below li…
13529 msgid "Once the dependencies have been installed, the ``python-kerberos`` wrapper can be install us…
13533 msgid "While Ansible has supported Kerberos auth through ``pywinrm`` for some time, optional featur…
13537 msgid "Configuring Host Kerberos"
13541 msgid "Once the dependencies have been installed, Kerberos needs to be configured so that it can co…
13545 msgid "To configure Kerberos, in the section that starts with:"
13549 msgid "Add the full domain name and the fully qualified domain names of the primary and secondary A…
13553 msgid "In the section that starts with:"
13557 msgid "Add a line like the following for each domain that Ansible needs access for:"
13561 msgid "You can configure other settings in this file such as the default domain. See `krb5.conf <ht…
13565 msgid "Automatic Kerberos Ticket Management"
13569 msgid "Ansible version 2.3 and later defaults to automatically managing Kerberos tickets when both …
13573 msgid "To disable automatic ticket management, set ``ansible_winrm_kinit_mode=manual`` via the inve…
13577 msgid "Automatic ticket management requires a standard ``kinit`` binary on the control host system …
13581 msgid "Manual Kerberos Ticket Management"
13585 msgid "To manually manage Kerberos tickets, the ``kinit`` binary is used. To obtain a new ticket th…
13589 msgid "The domain must match the configured Kerberos realm exactly, and must be in upper case."
13593 msgid "To see what tickets (if any) have been acquired, use the following command:"
13597 msgid "To destroy all the tickets that have been acquired, use the following command:"
13601 msgid "Troubleshooting Kerberos"
13605 msgid "Kerberos is reliant on a properly-configured environment to work. To troubleshoot Kerberos i…
13609 msgid "The hostname set for the Windows host is the FQDN and not an IP address."
13613 msgid "The forward and reverse DNS lookups are working properly in the domain. To test this, ping t…
13617 msgid "The Ansible host's clock is synchronized with the domain controller. Kerberos is time sensit…
13621 msgid "Ensure that the fully qualified domain name for the domain is configured in the ``krb5.conf`…
13625 msgid "If the domain name returned by ``klist`` is different from the one requested, an alias is be…
13629 msgid "If the default kerberos tooling has been replaced or modified (some IdM solutions may do thi…
13633 msgid "CredSSP authentication is a newer authentication protocol that allows credential delegation.…
13637 msgid "Because the username and password are sent to the server to be used for double hop authentic…
13641 msgid "CredSSP can be used for both local and domain accounts and also supports message encryption …
13645 msgid "To use CredSSP authentication, the host vars are configured like so:"
13649 msgid "There are some extra host variables that can be set as shown below::"
13653 msgid "CredSSP authentication is not enabled by default on a Windows host, but can be enabled by ru…
13657 msgid "Installing CredSSP Library"
13661 msgid "The ``requests-credssp`` wrapper can be installed using ``pip``:"
13665 msgid "CredSSP and TLS 1.2"
13669 msgid "By default the ``requests-credssp`` library is configured to authenticate over the TLS 1.2 p…
13673 msgid "There are two ways that older hosts can be used with CredSSP:"
13677 msgid "Install and enable a hotfix to enable TLS 1.2 support (recommended for Server 2008 R2 and Wi…
13681 msgid "Set ``ansible_winrm_credssp_disable_tlsv1_2=True`` in the inventory to run over TLS 1.0. Thi…
13685 msgid "See :ref:`winrm_tls12` for more information on how to enable TLS 1.2 on the Windows host."
13689 msgid "Set CredSSP Certificate"
13693 msgid "CredSSP works by encrypting the credentials through the TLS protocol and uses a self-signed …
13697 msgid "This certificate configuration is independent of the WinRM listener certificate. With CredSS…
13701 msgid "To explicitly set the certificate to use for CredSSP::"
13705 msgid "Non-Administrator Accounts"
13709 msgid "WinRM is configured by default to only allow connections from accounts in the local ``Admini…
13713 msgid "This will display an ACL editor, where new users or groups may be added. To run commands ove…
13717 msgid "While non-administrative accounts can be used with WinRM, most typical server administration…
13721 msgid "WinRM Encryption"
13725 msgid "By default WinRM will fail to work when running over an unencrypted channel. The WinRM proto…
13729 msgid "The ``ConfigureRemotingForAnsible.ps1`` creates a self-signed certificate and creates the li…
13733 msgid "If using HTTPS is not an option, then HTTP can be used when the authentication option is ``N…
13737 msgid "Message encryption over HTTP requires pywinrm>=0.3.0."
13741 msgid "A last resort is to disable the encryption requirement on the Windows host. This should only…
13745 msgid "Do not disable the encryption check unless it is absolutely required. Doing so could allow s…
13749 msgid "Inventory Options"
13753 msgid "Ansible's Windows support relies on a few standard variables to indicate the username, passw…
13757 msgid "When setting up the inventory, the following variables are required:"
13761 msgid "Using the variables above, Ansible will connect to the Windows host with Basic authenticatio…
13765 msgid "The following custom inventory variables are also supported for additional configuration of …
13769 msgid "``ansible_port``: The port WinRM will run over, HTTPS is ``5986`` which is the default while…
13773 msgid "``ansible_winrm_scheme``: Specify the connection scheme (``http`` or ``https``) to use for t…
13777 msgid "``ansible_winrm_path``: Specify an alternate path to the WinRM endpoint, Ansible uses ``/wsm…
13781 msgid "``ansible_winrm_realm``: Specify the realm to use for Kerberos authentication. If ``ansible_…
13785 msgid "``ansible_winrm_transport``: Specify one or more authentication transport options as a comma…
13789 msgid "``ansible_winrm_server_cert_validation``: Specify the server certificate validation mode (``…
13793 msgid "``ansible_winrm_operation_timeout_sec``: Increase the default timeout for WinRM operations, …
13797 msgid "``ansible_winrm_read_timeout_sec``: Increase the WinRM read timeout, Ansible uses ``30`` by …
13801 msgid "``ansible_winrm_message_encryption``: Specify the message encryption operation (``auto``, ``…
13805 msgid "``ansible_winrm_ca_trust_path``: Used to specify a different cacert container than the one u…
13809 msgid "``ansible_winrm_send_cbt``: When using ``ntlm`` or ``kerberos`` over HTTPS, the authenticati…
13813 msgid "``ansible_winrm_*``: Any additional keyword arguments supported by ``winrm.Protocol`` may be…
13817 msgid "In addition, there are also specific variables that need to be set for each authentication o…
13821 msgid "Ansible 2.0 has deprecated the \"ssh\" from ``ansible_ssh_user``, ``ansible_ssh_pass``, ``an…
13825 msgid "``ansible_winrm_message_encryption`` is different from transport encryption done over TLS. T…
13829 msgid "IPv6 Addresses"
13833 msgid "IPv6 addresses can be used instead of IPv4 addresses or hostnames. This option is normally s…
13837 msgid "When defining a host using an IPv6 address, just add the IPv6 address as you would an IPv4 a…
13841 msgid "The ipaddress library is only included by default in Python 3.x. To use IPv6 addresses in Py…
13845 msgid "HTTPS Certificate Validation"
13849 msgid "As part of the TLS protocol, the certificate is validated to ensure the host matches the sub…
13853 msgid "One of the more common ways of setting up a HTTPS listener in a domain environment is to use…
13857 msgid "To get Ansible to trust a Certificate Authority (CA) like AD CS, the issuer certificate of t…
13861 msgid "The CA chain can contain a single or multiple issuer certificates and each entry is containe…
13865 msgid "Each HTTP call is done by the Python requests library which does not use the systems built-i…
13869 msgid "TLS 1.2 Support"
13873 msgid "As WinRM runs over the HTTP protocol, using HTTPS means that the TLS protocol is used to enc…
13877 msgid "Commonly this is when the Windows host has not been configured to support TLS v1.2 but it co…
13881 msgid "Windows 8 and Windows Server 2012 come with TLS v1.2 installed and enabled by default but ol…
13885 msgid "There is a bug with the TLS 1.2 patch for Server 2008 which will stop Ansible from connectin…
13889 msgid "To verify what protocol the Windows host supports, you can run the following command on the …
13893 msgid "The output will contain information about the TLS session and the ``Protocol`` line will dis…
13897 msgid "If the host is returning ``TLSv1`` then it should be configured so that TLS v1.2 is enable. …
13901 msgid "The below Ansible tasks can also be used to enable TLS v1.2:"
13905 msgid "There are other ways to configure the TLS protocols as well as the cipher suites that are of…
13909 msgid "Due to the design of the WinRM protocol , there are a few limitations when using WinRM that …
13913 msgid "Credentials are not delegated for most authentication types, which causes authentication err…
13917 msgid "Many calls to the Windows Update API are blocked when running over WinRM."
13921 msgid "Some programs fail to install with WinRM due to no credential delegation or because they acc…
13925 msgid "Commands under WinRM are done under a non-interactive session, which can prevent certain com…
13929 msgid "You cannot run a process that interacts with ``DPAPI``, which is used by some installers (li…
13933 msgid "Some of these limitations can be mitigated by doing one of the following:"
13937 msgid "Set ``ansible_winrm_transport`` to ``credssp`` or ``kerberos`` (with ``ansible_winrm_kerbero…
13941 msgid "Use ``become`` to bypass all WinRM restrictions and run a command as it would locally. Unlik…
13945 msgid "Use a scheduled task to run a command which can be created with the ``win_scheduled_task`` m…
13948 #~ msgid "`webchat.freenode.net <https://webchat.freenode.net>`_"
13951 #~ msgid "`irc.freenode.net <http://irc.freenode.net>`_"
13954 #~ msgid "suboptions"