From fb5d2d10dba5cfea9579867df069288bae3d1400 Mon Sep 17 00:00:00 2001 From: Tim Bielawa Date: Tue, 7 Aug 2012 02:43:35 +0000 Subject: [PATCH] Refresh the use of 'note' to make it consistent. --- rst/api.rst | 8 +++++--- rst/modules.rst | 19 +++++++++++-------- rst/playbooks.rst | 33 +++++++++++++++++++++------------ rst/playbooks2.rst | 15 ++++++++++----- 4 files changed, 47 insertions(+), 28 deletions(-) diff --git a/rst/api.rst b/rst/api.rst index 64b24302d08..e14c9448620 100644 --- a/rst/api.rst +++ b/rst/api.rst @@ -148,9 +148,11 @@ Which could be executed just like this:: ansible webserver -m setup ansible webserver -m template -a "src=/tmp/motd.j2 dest=/etc/motd" -Note that the name 'webserver' came from cobbler, as did the variables for the config file. You can still -pass in your own variables like normal in Ansible, but variables from the external inventory script will -override any that have the same name. +.. note:: + The name 'webserver' came from cobbler, as did the variables for + the config file. You can still pass in your own variables like + normal in Ansible, but variables from the external inventory script + will override any that have the same name. So, with the template above (motd.j2), this would result in the following data being written to /etc/motd for system 'foo':: diff --git a/rst/modules.rst b/rst/modules.rst index 8497bb55fa2..34405bb15c4 100644 --- a/rst/modules.rst +++ b/rst/modules.rst @@ -141,9 +141,11 @@ be processed through the shell, so variables like "$HOME" and operations like "<", ">", "|", and "&" will not work. As such, all paths to commands must be fully qualified. -NOTE:: If you want to run a command through the shell (say you are using -'<', '>', '|', etc), you actually want the 'shell' module instead. -The 'command' module is much more secure as it's not affected by the user's environment. +.. note:: + If you want to run a command through the shell (say you are using + '<', '>', '|', etc), you actually want the 'shell' module instead. + The 'command' module is much more secure as it's not affected by + the user's environment. Example action from Ansible :doc:`playbooks`:: @@ -730,11 +732,12 @@ but runs the command through the user's configured shell on the remote node. The given command will be executed on all selected nodes. -NOTE:: If you want to execute a command securely and predicably, it may -be better to use the 'command' module instead. Best practices -when writing playbooks will follow the trend of using 'command' -unless 'shell' is explicitly required. When running ad-hoc commands, -use your best judgement. +.. note:: + If you want to execute a command securely and predicably, it may be + better to use the 'command' module instead. Best practices when + writing playbooks will follow the trend of using 'command' unless + 'shell' is explicitly required. When running ad-hoc commands, use + your best judgement. Example action from a playbook:: diff --git a/rst/playbooks.rst b/rst/playbooks.rst index 7b42c93795a..a53b66c6d83 100644 --- a/rst/playbooks.rst +++ b/rst/playbooks.rst @@ -95,12 +95,18 @@ If you need to specify a password to sudo, run `ansible-playbook` with ``--ask-s If you run a sudo playbook and the playbook seems to hang, it's probably stuck at the sudo prompt. Just `Control-C` to kill it and run it again with `-K`. -NOTE: When using `sudo_user` to a user other than root, the module arguments are briefly written into -a random tempfile in /tmp. These are deleted immediately after the command is executed. This only -occurs when sudoing from a user like 'bob' to 'timmy', not when going from 'bob' to 'root', or -logging in directly as 'bob' or 'root'. If this concerns you that this data is briefly readable -(not writeable), avoid transferring uncrypted passwords with `sudo_user` set. In other cases, '/tmp' is not used and -this does not come into play. Ansible also takes care to not log password parameters. +.. important:: + + When using `sudo_user` to a user other than root, the module + arguments are briefly written into a random tempfile in /tmp. + These are deleted immediately after the command is executed. This + only occurs when sudoing from a user like 'bob' to 'timmy', not + when going from 'bob' to 'root', or logging in directly as 'bob' or + 'root'. If this concerns you that this data is briefly readable + (not writeable), avoid transferring uncrypted passwords with + `sudo_user` set. In other cases, '/tmp' is not used and this does + not come into play. Ansible also takes care to not log password + parameters. Vars section ++++++++++++ @@ -318,12 +324,15 @@ of a play:: You can mix in includes along with your regular non-included tasks and handlers. -NOTE:: you can not conditionally path the location to an include file, like you can -with 'vars_files'. If you find yourself needing to do this, consider how you can -restructure your playbook to be more class/role oriented. This is to say you cannot -use a 'fact' to decide what include file to use. All hosts contained within the play -are going to get the same tasks. ('only_if' provides some ability for hosts to conditionally -skip tasks). +.. note:: + + You can not conditionally path the location to an include file, + like you can with 'vars_files'. If you find yourself needing to do + this, consider how you can restructure your playbook to be more + class/role oriented. This is to say you cannot use a 'fact' to + decide what include file to use. All hosts contained within the + play are going to get the same tasks. ('only_if' provides some + ability for hosts to conditionally skip tasks). Executing A Playbook ```````````````````` diff --git a/rst/playbooks2.rst b/rst/playbooks2.rst index f0c5b47b9b4..11bd7726971 100644 --- a/rst/playbooks2.rst +++ b/rst/playbooks2.rst @@ -83,8 +83,10 @@ assigned to another node, it's easy to do so within a template or even an action ${hostvars.hostname.factname} -NOTE: No database or other complex system is required to exchange data between hosts. The hosts that you -want to reference data from must be included in either the current play or any previous play. +.. note:: + No database or other complex system is required to exchange data + between hosts. The hosts that you want to reference data from must + be included in either the current play or any previous play. Additionally, *group_names* is a list (array) of all the groups the current host is in. This can be used in templates using Jinja2 syntax to make template source files that vary based on the group membership (or role) of the host:: @@ -140,7 +142,9 @@ The contents of each variables file is a simple YAML dictionary, like this:: somevar: somevalue password: magic -NOTE: It's also possible to keep per-host and per-group variables in very similar files, this is covered in :ref:`patterns`. +.. note:: + It's also possible to keep per-host and per-group variables in very + similar files, this is covered in :ref:`patterns`. Prompting For Sensitive Data ```````````````````````````` @@ -256,8 +260,9 @@ but it is easily handled with a minimum of syntax in an Ansible Playbook:: - name: make sure apache is running action: service name=$apache state=running -Note that a variable (`$facter_operatingsystem`) is being interpolated into the list of -filenames being defined for vars_files. +.. note:: + The variable (`$facter_operatingsystem`) is being interpolated into + the list of filenames being defined for vars_files. As a reminder, the various YAML files contain just keys and values::