diff --git a/doc/ref/auth/all/index.rst b/doc/ref/auth/all/index.rst
index ba2f6f803c95..f12d6f28bff5 100644
--- a/doc/ref/auth/all/index.rst
+++ b/doc/ref/auth/all/index.rst
@@ -1,8 +1,8 @@
.. _all-salt.auth:
-=================================
-Full list of builtin auth modules
-=================================
+============
+auth modules
+============
.. currentmodule:: salt.auth
diff --git a/doc/ref/beacons/all/index.rst b/doc/ref/beacons/all/index.rst
index e985d9f3fa9e..f1913c839807 100644
--- a/doc/ref/beacons/all/index.rst
+++ b/doc/ref/beacons/all/index.rst
@@ -1,8 +1,8 @@
.. _all-salt.beacons:
-===================================
-Full list of builtin beacon modules
-===================================
+==============
+beacon modules
+==============
.. currentmodule:: salt.beacons
diff --git a/doc/ref/engines/all/index.rst b/doc/ref/engines/all/index.rst
index 40ac114b96d9..5da2cacab785 100644
--- a/doc/ref/engines/all/index.rst
+++ b/doc/ref/engines/all/index.rst
@@ -1,8 +1,8 @@
.. _all-salt.engines:
-===================================
-Full list of builtin engine modules
-===================================
+==============
+engine modules
+==============
.. currentmodule:: salt.engines
diff --git a/doc/ref/file_server/all/index.rst b/doc/ref/file_server/all/index.rst
index 3ce9ea90a572..c6c13e291bc3 100644
--- a/doc/ref/file_server/all/index.rst
+++ b/doc/ref/file_server/all/index.rst
@@ -1,8 +1,8 @@
.. _all-salt.fileserver:
-=======================================
-Full list of builtin fileserver modules
-=======================================
+==================
+fileserver modules
+==================
.. currentmodule:: salt.fileserver
diff --git a/doc/ref/grains/all/index.rst b/doc/ref/grains/all/index.rst
index abe957a7674a..1a14baa3cbd5 100644
--- a/doc/ref/grains/all/index.rst
+++ b/doc/ref/grains/all/index.rst
@@ -1,8 +1,8 @@
.. _all-salt.grains:
-===================================
-Full list of builtin grains modules
-===================================
+==============
+grains modules
+==============
.. currentmodule:: salt.grains
diff --git a/doc/ref/modules/all/index.rst b/doc/ref/modules/all/index.rst
index f9e32e385ad9..22ca010a901b 100644
--- a/doc/ref/modules/all/index.rst
+++ b/doc/ref/modules/all/index.rst
@@ -1,8 +1,8 @@
.. _all-salt_modules:
-======================================
-Full list of builtin execution modules
-======================================
+=================
+execution modules
+=================
.. admonition:: Virtual modules
diff --git a/doc/ref/netapi/all/index.rst b/doc/ref/netapi/all/index.rst
index e978e85ccb3a..a05ec291e29d 100644
--- a/doc/ref/netapi/all/index.rst
+++ b/doc/ref/netapi/all/index.rst
@@ -1,8 +1,8 @@
.. _all-netapi-modules:
-===========================
-Full list of netapi modules
-===========================
+==============
+netapi modules
+==============
.. toctree::
:maxdepth: 2
diff --git a/doc/ref/output/all/index.rst b/doc/ref/output/all/index.rst
index acee155d6f73..954753bb3613 100644
--- a/doc/ref/output/all/index.rst
+++ b/doc/ref/output/all/index.rst
@@ -1,8 +1,8 @@
.. _all-salt.output:
-===================================
-Full list of builtin output modules
-===================================
+==============
+output modules
+==============
Follow one of the below links for further information and examples
diff --git a/doc/ref/pillar/all/index.rst b/doc/ref/pillar/all/index.rst
index a4d331633224..c17f7616c36b 100644
--- a/doc/ref/pillar/all/index.rst
+++ b/doc/ref/pillar/all/index.rst
@@ -1,8 +1,8 @@
.. _all-salt.pillars:
-===================================
-Full list of builtin pillar modules
-===================================
+==============
+pillar modules
+==============
.. currentmodule:: salt.pillar
diff --git a/doc/ref/proxy/all/index.rst b/doc/ref/proxy/all/index.rst
index 139595381eb9..28deb2c66c6e 100644
--- a/doc/ref/proxy/all/index.rst
+++ b/doc/ref/proxy/all/index.rst
@@ -1,8 +1,8 @@
.. _all-salt.proxy:
-==================================
-Full list of builtin proxy modules
-==================================
+=============
+proxy modules
+=============
.. currentmodule:: salt.proxy
diff --git a/doc/ref/queues/all/index.rst b/doc/ref/queues/all/index.rst
index 5507a26ce749..2d579aa01558 100644
--- a/doc/ref/queues/all/index.rst
+++ b/doc/ref/queues/all/index.rst
@@ -1,8 +1,8 @@
.. _all-salt.queues:
-===========================
-Full list of builtin queues
-===========================
+=============
+queue modules
+=============
.. currentmodule:: salt.queues
diff --git a/doc/ref/renderers/all/index.rst b/doc/ref/renderers/all/index.rst
index cf34c77e69bd..e62b7f56f0e1 100644
--- a/doc/ref/renderers/all/index.rst
+++ b/doc/ref/renderers/all/index.rst
@@ -1,8 +1,8 @@
.. _all-salt.renderers:
-=====================================
-Full list of builtin renderer modules
-=====================================
+================
+renderer modules
+================
.. currentmodule:: salt.renderers
diff --git a/doc/ref/returners/all/index.rst b/doc/ref/returners/all/index.rst
index 6dd001aa5d93..2e5e97f035e8 100644
--- a/doc/ref/returners/all/index.rst
+++ b/doc/ref/returners/all/index.rst
@@ -1,8 +1,8 @@
.. _all-salt.returners:
-=====================================
-Full list of builtin returner modules
-=====================================
+================
+returner modules
+================
.. currentmodule:: salt.returners
diff --git a/doc/ref/roster/all/index.rst b/doc/ref/roster/all/index.rst
index 063acd7156c6..19446af8d017 100644
--- a/doc/ref/roster/all/index.rst
+++ b/doc/ref/roster/all/index.rst
@@ -1,8 +1,8 @@
.. _all-salt.roster:
-===================================
-Full list of builtin roster modules
-===================================
+==============
+roster modules
+==============
.. currentmodule:: salt.roster
diff --git a/doc/ref/runners/all/index.rst b/doc/ref/runners/all/index.rst
index e906c1d6057e..32643b8e6313 100644
--- a/doc/ref/runners/all/index.rst
+++ b/doc/ref/runners/all/index.rst
@@ -1,8 +1,8 @@
.. _all-salt.runners:
-===========================
-Full list of runner modules
-===========================
+==============
+runner modules
+==============
.. currentmodule:: salt.runners
diff --git a/doc/ref/sdb/all/index.rst b/doc/ref/sdb/all/index.rst
index 8e6bdbb7a6a6..f7ce58fb7cd4 100644
--- a/doc/ref/sdb/all/index.rst
+++ b/doc/ref/sdb/all/index.rst
@@ -1,8 +1,8 @@
.. _all-salt.sdb:
-================================
-Full list of builtin sdb modules
-================================
+===========
+sdb modules
+===========
.. currentmodule:: salt.sdb
diff --git a/doc/ref/serializers/all/index.rst b/doc/ref/serializers/all/index.rst
index a9eb50067778..261ccb01f695 100644
--- a/doc/ref/serializers/all/index.rst
+++ b/doc/ref/serializers/all/index.rst
@@ -1,8 +1,8 @@
.. _all-salt.serializers:
-================================
-Full list of builtin serializers
-================================
+==================
+serializer modules
+==================
.. currentmodule:: salt.serializers
diff --git a/doc/ref/states/all/index.rst b/doc/ref/states/all/index.rst
index 3288a1c672ee..3e10009d0050 100644
--- a/doc/ref/states/all/index.rst
+++ b/doc/ref/states/all/index.rst
@@ -1,8 +1,8 @@
.. _all-salt.states:
-==================================
-Full list of builtin state modules
-==================================
+=============
+state modules
+=============
.. currentmodule:: salt.states
diff --git a/doc/ref/thorium/all/index.rst b/doc/ref/thorium/all/index.rst
index 791e0258fdcb..9f694775e3db 100644
--- a/doc/ref/thorium/all/index.rst
+++ b/doc/ref/thorium/all/index.rst
@@ -1,8 +1,8 @@
.. _all-salt.thorium:
-====================================
-Full list of builtin thorium modules
-====================================
+===============
+thorium modules
+===============
.. currentmodule:: salt.thorium
diff --git a/doc/ref/tops/all/index.rst b/doc/ref/tops/all/index.rst
index b7c19d5ce3a0..7072924d5c34 100644
--- a/doc/ref/tops/all/index.rst
+++ b/doc/ref/tops/all/index.rst
@@ -1,8 +1,8 @@
.. _all-salt.tops:
-========================================
-Full list of builtin master tops modules
-========================================
+===================
+master tops modules
+===================
.. currentmodule:: salt.tops
diff --git a/doc/ref/wheel/all/index.rst b/doc/ref/wheel/all/index.rst
index 73e6d873a692..500c3d5c9eea 100644
--- a/doc/ref/wheel/all/index.rst
+++ b/doc/ref/wheel/all/index.rst
@@ -1,8 +1,8 @@
.. _all-salt.wheel:
-==================================
-Full list of builtin wheel modules
-==================================
+=============
+wheel modules
+=============
.. currentmodule:: salt.wheel
diff --git a/doc/topics/jinja/index.rst b/doc/topics/jinja/index.rst
new file mode 100644
index 000000000000..adfcdc168816
--- /dev/null
+++ b/doc/topics/jinja/index.rst
@@ -0,0 +1,364 @@
+.. _jinja:
+
+===================
+Understanding Jinja
+===================
+
+`Jinja `_ is the default templating language
+in SLS files.
+
+Jinja in States
+===============
+
+.. _Jinja: http://jinja.pocoo.org/docs/templates/
+
+Jinja is evaluated before YAML, which means it is evaluated before the States
+are run.
+
+The most basic usage of Jinja in state files is using control structures to
+wrap conditional or redundant state elements:
+
+.. code-block:: yaml
+
+ {% if grains['os'] != 'FreeBSD' %}
+ tcsh:
+ pkg:
+ - installed
+ {% endif %}
+
+ motd:
+ file.managed:
+ {% if grains['os'] == 'FreeBSD' %}
+ - name: /etc/motd
+ {% elif grains['os'] == 'Debian' %}
+ - name: /etc/motd.tail
+ {% endif %}
+ - source: salt://motd
+
+In this example, the first if block will only be evaluated on minions that
+aren't running FreeBSD, and the second block changes the file name based on the
+*os* grain.
+
+Writing **if-else** blocks can lead to very redundant state files however. In
+this case, using :doc:`pillars`, or using a previously
+defined variable might be easier:
+
+.. code-block:: yaml
+
+ {% set motd = ['/etc/motd'] %}
+ {% if grains['os'] == 'Debian' %}
+ {% set motd = ['/etc/motd.tail', '/var/run/motd'] %}
+ {% endif %}
+
+ {% for motdfile in motd %}
+ {{ motdfile }}:
+ file.managed:
+ - source: salt://motd
+ {% endfor %}
+
+Using a variable set by the template, the `for loop`_ will iterate over the
+list of MOTD files to update, adding a state block for each file.
+
+The filter_by function can also be used to set variables based on grains:
+
+.. code-block:: yaml
+
+ {% set auditd = salt['grains.filter_by']({
+ 'RedHat': { 'package': 'audit' },
+ 'Debian': { 'package': 'auditd' },
+ }) %}
+
+.. _`for loop`: http://jinja.pocoo.org/docs/templates/#for
+
+Include and Import
+==================
+
+Includes and imports_ can be used to share common, reusable state configuration
+between state files and between files.
+
+.. code-block:: yaml
+
+ {% from 'lib.sls' import test %}
+
+This would import the ``test`` template variable or macro, not the ``test``
+state element, from the file ``lib.sls``. In the case that the included file
+performs checks again grains, or something else that requires context, passing
+the context into the included file is required:
+
+.. code-block:: yaml
+
+ {% from 'lib.sls' import test with context %}
+
+Including Context During Include/Import
+---------------------------------------
+
+By adding ``with context`` to the include/import directive, the
+current context can be passed to an included/imported template.
+
+.. code-block:: yaml
+
+ {% import 'openssl/vars.sls' as ssl with context %}
+
+
+.. _imports: http://jinja.pocoo.org/docs/templates/#import
+
+Macros
+======
+
+Macros_ are helpful for eliminating redundant code. Macros are most useful as
+mini-templates to repeat blocks of strings with a few parameterized variables.
+Be aware that stripping whitespace from the template block, as well as
+contained blocks, may be necessary to emulate a variable return from the macro.
+
+.. code-block:: yaml
+
+ # init.sls
+ {% from 'lib.sls' import pythonpkg with context %}
+
+ python-virtualenv:
+ pkg.installed:
+ - name: {{ pythonpkg('virtualenv') }}
+
+ python-fabric:
+ pkg.installed:
+ - name: {{ pythonpkg('fabric') }}
+
+.. code-block:: yaml
+
+ # lib.sls
+ {% macro pythonpkg(pkg) -%}
+ {%- if grains['os'] == 'FreeBSD' -%}
+ py27-{{ pkg }}
+ {%- elif grains['os'] == 'Debian' -%}
+ python-{{ pkg }}
+ {%- endif -%}
+ {%- endmacro %}
+
+This would define a macro_ that would return a string of the full package name,
+depending on the packaging system's naming convention. The whitespace of the
+macro was eliminated, so that the macro would return a string without line
+breaks, using `whitespace control`_.
+
+Template Inheritance
+====================
+
+`Template inheritance`_ works fine from state files and files. The search path
+starts at the root of the state tree or pillar.
+
+.. _`Template inheritance`: http://jinja.pocoo.org/docs/templates/#template-inheritance
+.. _`Macros`: http://jinja.pocoo.org/docs/templates/#macros
+.. _`macro`: http://jinja.pocoo.org/docs/templates/#macros
+.. _`whitespace control`: http://jinja.pocoo.org/docs/templates/#whitespace-control
+
+Filters
+=======
+
+Saltstack extends `builtin filters`_ with these custom filters:
+
+strftime
+ Converts any time related object into a time based string. It requires a
+ valid :ref:`strftime directives `. An
+ :ref:`exhaustive list ` can be found in
+ the official Python documentation.
+
+ .. code-block:: yaml
+
+ {% set curtime = None | strftime() %}
+
+ Fuzzy dates require the `timelib`_ Python module is installed.
+
+ .. code-block:: yaml
+
+ {{ "2002/12/25"|strftime("%y") }}
+ {{ "1040814000"|strftime("%Y-%m-%d") }}
+ {{ datetime|strftime("%u") }}
+ {{ "tomorrow"|strftime }}
+
+sequence
+ Ensure that parsed data is a sequence.
+
+yaml_encode
+ Serializes a single object into a YAML scalar with any necessary
+ handling for escaping special characters. This will work for any
+ scalar YAML data type: ints, floats, timestamps, booleans, strings,
+ unicode. It will *not* work for multi-objects such as sequences or
+ maps.
+
+ .. code-block:: yaml
+
+ {%- set bar = 7 %}
+ {%- set baz = none %}
+ {%- set zip = true %}
+ {%- set zap = 'The word of the day is "salty"' %}
+
+ {%- load_yaml as foo %}
+ bar: {{ bar|yaml_encode }}
+ baz: {{ baz|yaml_encode }}
+ baz: {{ zip|yaml_encode }}
+ baz: {{ zap|yaml_encode }}
+ {%- endload %}
+
+ In the above case ``{{ bar }}`` and ``{{ foo.bar }}`` should be
+ identical and ``{{ baz }}`` and ``{{ foo.baz }}`` should be
+ identical.
+
+yaml_dquote
+ Serializes a string into a properly-escaped YAML double-quoted
+ string. This is useful when the contents of a string are unknown
+ and may contain quotes or unicode that needs to be preserved. The
+ resulting string will be emitted with opening and closing double
+ quotes.
+
+ .. code-block:: yaml
+
+ {%- set bar = '"The quick brown fox . . ."' %}
+ {%- set baz = 'The word of the day is "salty".' %}
+
+ {%- load_yaml as foo %}
+ bar: {{ bar|yaml_dquote }}
+ baz: {{ baz|yaml_dquote }}
+ {%- endload %}
+
+ In the above case ``{{ bar }}`` and ``{{ foo.bar }}`` should be
+ identical and ``{{ baz }}`` and ``{{ foo.baz }}`` should be
+ identical. If variable contents are not guaranteed to be a string
+ then it is better to use ``yaml_encode`` which handles all YAML
+ scalar types.
+
+yaml_squote
+ Similar to the ``yaml_dquote`` filter but with single quotes. Note
+ that YAML only allows special escapes inside double quotes so
+ ``yaml_squote`` is not nearly as useful (viz. you likely want to
+ use ``yaml_encode`` or ``yaml_dquote``).
+
+.. _`builtin filters`: http://jinja.pocoo.org/docs/templates/#builtin-filters
+.. _`timelib`: https://github.com/pediapress/timelib/
+
+Jinja in Files
+==============
+
+Jinja_ can be used in the same way in managed files:
+
+.. code-block:: yaml
+
+ # redis.sls
+ /etc/redis/redis.conf:
+ file.managed:
+ - source: salt://redis.conf
+ - template: jinja
+ - context:
+ bind: 127.0.0.1
+
+.. code-block:: yaml
+
+ # lib.sls
+ {% set port = 6379 %}
+
+.. code-block:: ini
+
+ # redis.conf
+ {% from 'lib.sls' import port with context %}
+ port {{ port }}
+ bind {{ bind }}
+
+As an example, configuration was pulled from the file context and from an
+external template file.
+
+.. note::
+
+ Macros and variables can be shared across templates. They should not be
+ starting with one or more underscores, and should be managed by one of the
+ following tags: `macro`, `set`, `load_yaml`, `load_json`, `import_yaml` and
+ `import_json`.
+
+Escaping Jinja
+==============
+
+Occasionally, it may be necessary to escape Jinja syntax. There are two ways to
+to do this in Jinja. One is escaping individual variables or strings and the
+other is to escape entire blocks.
+
+To escape a string commonly used in Jinja syntax such as ``{{``, you can use the
+following syntax:
+
+.. code-block:: jinja
+
+ {{ '{{' }}
+
+For larger blocks that contain Jinja syntax that needs to be escaped, you can use
+raw blocks:
+
+.. code-block:: jinja
+
+ {% raw %}
+ some text that contains jinja characters that need to be escaped
+ {% endraw %}
+
+See the `Escaping`_ section of Jinja's documentation to learn more.
+
+A real-word example of needing to use raw tags to escape a larger block of code
+is when using ``file.managed`` with the ``contents_pillar`` option to manage
+files that contain something like consul-template, which shares a syntax subset
+with Jinja. Raw blocks are necessary here because the Jinja in the pillar would
+be rendered before the file.managed is ever called, so the Jinja syntax must be
+escaped:
+
+.. code-block:: jinja
+
+ {% raw %}
+ - contents_pillar: |
+ job "example-job" {
+
+ task "example" {
+ driver = "docker"
+
+ config {
+ image = "docker-registry.service.consul:5000/example-job:{{key "nomad/jobs/example-job/version"}}"
+
+ {% endraw %}
+
+.. _`Escaping`: http://jinja.pocoo.org/docs/dev/templates/#escaping
+
+Calling Salt Functions
+======================
+
+The Jinja renderer provides a shorthand lookup syntax for the ``salt``
+dictionary of :term:`execution function `.
+
+.. versionadded:: 2014.7.0
+
+.. code-block:: yaml
+
+ # The following two function calls are equivalent.
+ {{ salt['cmd.run']('whoami') }}
+ {{ salt.cmd.run('whoami') }}
+
+Debugging
+=========
+
+The ``show_full_context`` function can be used to output all variables present
+in the current Jinja context.
+
+.. versionadded:: 2014.7.0
+
+.. code-block:: yaml
+
+ Context is: {{ show_full_context() }}
+
+Custom Execution Modules
+========================
+
+Custom execution modules can be used to supplement or replace complex Jinja. Many
+tasks that require complex looping and logic are trivial when using Python
+in a Salt execution module. Salt execution modules are easy to write and
+distribute to Salt minions.
+
+:ref:`Writing Execution Modules `
+
+Functions in custom execution modules are available in the Salt execution
+module dictionary just like the built-in execution modules:
+
+.. code-block:: yaml
+
+ {{ salt['my_custom_module.my_custom_function']() }}
+
diff --git a/doc/topics/targeting/nodegroups.rst b/doc/topics/targeting/nodegroups.rst
index 3024d7f5c8cc..998ac742e6cf 100644
--- a/doc/topics/targeting/nodegroups.rst
+++ b/doc/topics/targeting/nodegroups.rst
@@ -52,7 +52,7 @@ To match a nodegroup on the CLI, use the ``-N`` command-line option:
.. note::
- The ``N@`` classifier cannot be used in compound mathes within the CLI or
+ The ``N@`` classifier cannot be used in compound matches within the CLI or
:term:`top file`, it is only recognized in the :conf_master:`nodegroups`
master config file parameter.
diff --git a/doc/topics/tutorials/pillar.rst b/doc/topics/tutorials/pillar.rst
index 4ca1d6aefd85..18baaa7208f5 100644
--- a/doc/topics/tutorials/pillar.rst
+++ b/doc/topics/tutorials/pillar.rst
@@ -324,11 +324,14 @@ specified list, notice the nested pillar dict:
salt '*' state.apply edit.vim pillar='{"pkgs": {"vim": "telnet"}}'
-.. note::
-
- This will attempt to install telnet on your minions, feel free to
- uninstall the package or replace telnet value with anything else.
+This will attempt to install telnet on your minions, feel free to
+uninstall the package or replace telnet value with anything else.
+.. note::
+ Be aware that when sending sensitive data via pillar on the command-line
+ that the publication containing that data will be received by all minions
+ and will not be restricted to the targeted minions. This may represent
+ a security concern in some cases.
More On Pillar
==============
diff --git a/doc/topics/using_salt.rst b/doc/topics/using_salt.rst
index caf90ce010ee..f5f494f58651 100644
--- a/doc/topics/using_salt.rst
+++ b/doc/topics/using_salt.rst
@@ -14,6 +14,7 @@ This section describes the fundamental components and concepts that you need to
../ref/runners/index
engines/index
yaml/index
+ jinja/index
troubleshooting/index
../faq
best_practices
diff --git a/doc/topics/yaml/index.rst b/doc/topics/yaml/index.rst
index bfed910550af..54600d1e2778 100644
--- a/doc/topics/yaml/index.rst
+++ b/doc/topics/yaml/index.rst
@@ -1,3 +1,6 @@
+.. _yaml:
+
+==================
Understanding YAML
==================
@@ -107,4 +110,10 @@ Learning More
One easy way to learn more about how YAML gets rendered into Python data structures is
to use an online YAML parser to see the Python output.
-One excellent choice for experimenting with YAML parsing is: http://yaml-online-parser.appspot.com/
\ No newline at end of file
+One excellent choice for experimenting with YAML parsing is: http://yaml-online-parser.appspot.com/
+
+Templating
+----------
+Jinja statements and expressions are allowed by default in SLS files. See
+:ref:`Understanding Jinja `.
+
diff --git a/salt/netapi/rest_cherrypy/app.py b/salt/netapi/rest_cherrypy/app.py
index a06c3708cf2d..cda4ff84e1ab 100644
--- a/salt/netapi/rest_cherrypy/app.py
+++ b/salt/netapi/rest_cherrypy/app.py
@@ -247,6 +247,22 @@
.. |200| replace:: success
.. |401| replace:: authentication required
.. |406| replace:: requested Content-Type not available
+
+A Note About Curl
+=================
+
+When sending passwords and data that might need to be urlencoded, you must set
+the ``-d`` flag to indicate the content type, and the ``--data-urlencode`` flag
+to urlencode the input.
+
+.. code-block:: bash
+
+ curl -ksi http://localhost:8000/login \\
+ -H "Accept: application/json" \\
+ -d username='myapiuser' \\
+ --data-urlencode password='1234+' \\
+ -d eauth='pam'
+
'''
# We need a custom pylintrc here...
# pylint: disable=W0212,E1101,C0103,R0201,W0221,W0613
diff --git a/salt/renderers/jinja.py b/salt/renderers/jinja.py
index 4413e9d6ebf7..0bab045a0e25 100644
--- a/salt/renderers/jinja.py
+++ b/salt/renderers/jinja.py
@@ -2,319 +2,7 @@
'''
Jinja loading utils to enable a more powerful backend for jinja templates
-Jinja in States
-===============
-
-.. _Jinja: http://jinja.pocoo.org/docs/templates/
-
-The most basic usage of Jinja in state files is using control structures to
-wrap conditional or redundant state elements:
-
-.. code-block:: yaml
-
- {% if grains['os'] != 'FreeBSD' %}
- tcsh:
- pkg:
- - installed
- {% endif %}
-
- motd:
- file.managed:
- {% if grains['os'] == 'FreeBSD' %}
- - name: /etc/motd
- {% elif grains['os'] == 'Debian' %}
- - name: /etc/motd.tail
- {% endif %}
- - source: salt://motd
-
-In this example, the first if block will only be evaluated on minions that
-aren't running FreeBSD, and the second block changes the file name based on the
-*os* grain.
-
-Writing **if-else** blocks can lead to very redundant state files however. In
-this case, using :doc:`pillars`, or using a previously
-defined variable might be easier:
-
-.. code-block:: yaml
-
- {% set motd = ['/etc/motd'] %}
- {% if grains['os'] == 'Debian' %}
- {% set motd = ['/etc/motd.tail', '/var/run/motd'] %}
- {% endif %}
-
- {% for motdfile in motd %}
- {{ motdfile }}:
- file.managed:
- - source: salt://motd
- {% endfor %}
-
-Using a variable set by the template, the `for loop`_ will iterate over the
-list of MOTD files to update, adding a state block for each file.
-
-.. _`for loop`: http://jinja.pocoo.org/docs/templates/#for
-
-Include and Import
-==================
-
-Includes and imports_ can be used to share common, reusable state configuration
-between state files and between files.
-
-.. code-block:: yaml
-
- {% from 'lib.sls' import test %}
-
-This would import the ``test`` template variable or macro, not the ``test``
-state element, from the file ``lib.sls``. In the case that the included file
-performs checks again grains, or something else that requires context, passing
-the context into the included file is required:
-
-.. code-block:: yaml
-
- {% from 'lib.sls' import test with context %}
-
-.. _imports: http://jinja.pocoo.org/docs/templates/#import
-
-Macros
-======
-
-Macros_ are helpful for eliminating redundant code, however stripping whitespace
-from the template block, as well as contained blocks, may be necessary to
-emulate a variable return from the macro.
-
-.. code-block:: yaml
-
- # init.sls
- {% from 'lib.sls' import pythonpkg with context %}
-
- python-virtualenv:
- pkg.installed:
- - name: {{ pythonpkg('virtualenv') }}
-
- python-fabric:
- pkg.installed:
- - name: {{ pythonpkg('fabric') }}
-
-.. code-block:: yaml
-
- # lib.sls
- {% macro pythonpkg(pkg) -%}
- {%- if grains['os'] == 'FreeBSD' -%}
- py27-{{ pkg }}
- {%- elif grains['os'] == 'Debian' -%}
- python-{{ pkg }}
- {%- endif -%}
- {%- endmacro %}
-
-This would define a macro_ that would return a string of the full package name,
-depending on the packaging system's naming convention. The whitespace of the
-macro was eliminated, so that the macro would return a string without line
-breaks, using `whitespace control`_.
-
-Template Inheritance
-====================
-
-`Template inheritance`_ works fine from state files and files. The search path
-starts at the root of the state tree or pillar.
-
-.. _`Template inheritance`: http://jinja.pocoo.org/docs/templates/#template-inheritance
-.. _`Macros`: http://jinja.pocoo.org/docs/templates/#macros
-.. _`macro`: http://jinja.pocoo.org/docs/templates/#macros
-.. _`whitespace control`: http://jinja.pocoo.org/docs/templates/#whitespace-control
-
-Filters
-=======
-
-Saltstack extends `builtin filters`_ with these custom filters:
-
-strftime
- Converts any time related object into a time based string. It requires a
- valid :ref:`strftime directives `. An
- :ref:`exhaustive list ` can be found in
- the official Python documentation.
-
- .. code-block:: yaml
-
- {% set curtime = None | strftime() %}
-
- Fuzzy dates require the `timelib`_ Python module is installed.
-
- .. code-block:: yaml
-
- {{ "2002/12/25"|strftime("%y") }}
- {{ "1040814000"|strftime("%Y-%m-%d") }}
- {{ datetime|strftime("%u") }}
- {{ "tomorrow"|strftime }}
-
-sequence
- Ensure that parsed data is a sequence.
-
-yaml_encode
- Serializes a single object into a YAML scalar with any necessary
- handling for escaping special characters. This will work for any
- scalar YAML data type: ints, floats, timestamps, booleans, strings,
- unicode. It will *not* work for multi-objects such as sequences or
- maps.
-
- .. code-block:: yaml
-
- {%- set bar = 7 %}
- {%- set baz = none %}
- {%- set zip = true %}
- {%- set zap = 'The word of the day is "salty"' %}
-
- {%- load_yaml as foo %}
- bar: {{ bar|yaml_encode }}
- baz: {{ baz|yaml_encode }}
- baz: {{ zip|yaml_encode }}
- baz: {{ zap|yaml_encode }}
- {%- endload %}
-
- In the above case ``{{ bar }}`` and ``{{ foo.bar }}`` should be
- identical and ``{{ baz }}`` and ``{{ foo.baz }}`` should be
- identical.
-
-yaml_dquote
- Serializes a string into a properly-escaped YAML double-quoted
- string. This is useful when the contents of a string are unknown
- and may contain quotes or unicode that needs to be preserved. The
- resulting string will be emitted with opening and closing double
- quotes.
-
- .. code-block:: yaml
-
- {%- set bar = '"The quick brown fox . . ."' %}
- {%- set baz = 'The word of the day is "salty".' %}
-
- {%- load_yaml as foo %}
- bar: {{ bar|yaml_dquote }}
- baz: {{ baz|yaml_dquote }}
- {%- endload %}
-
- In the above case ``{{ bar }}`` and ``{{ foo.bar }}`` should be
- identical and ``{{ baz }}`` and ``{{ foo.baz }}`` should be
- identical. If variable contents are not guaranteed to be a string
- then it is better to use ``yaml_encode`` which handles all YAML
- scalar types.
-
-yaml_squote
- Similar to the ``yaml_dquote`` filter but with single quotes. Note
- that YAML only allows special escapes inside double quotes so
- ``yaml_squote`` is not nearly as useful (viz. you likely want to
- use ``yaml_encode`` or ``yaml_dquote``).
-
-.. _`builtin filters`: http://jinja.pocoo.org/docs/templates/#builtin-filters
-.. _`timelib`: https://github.com/pediapress/timelib/
-
-Jinja in Files
-==============
-
-Jinja_ can be used in the same way in managed files:
-
-.. code-block:: yaml
-
- # redis.sls
- /etc/redis/redis.conf:
- file.managed:
- - source: salt://redis.conf
- - template: jinja
- - context:
- bind: 127.0.0.1
-
-.. code-block:: yaml
-
- # lib.sls
- {% set port = 6379 %}
-
-.. code-block:: ini
-
- # redis.conf
- {% from 'lib.sls' import port with context %}
- port {{ port }}
- bind {{ bind }}
-
-As an example, configuration was pulled from the file context and from an
-external template file.
-
-.. note::
-
- Macros and variables can be shared across templates. They should not be
- starting with one or more underscores, and should be managed by one of the
- following tags: `macro`, `set`, `load_yaml`, `load_json`, `import_yaml` and
- `import_json`.
-
-Escaping Jinja
-==============
-
-Occasionally, it may be necessary to escape Jinja syntax. There are two ways to
-to do this in Jinja. One is escaping individual variables or strings and the
-other is to escape entire blocks.
-
-To escape a string commonly used in Jinja syntax such as ``{{``, you can use the
-following syntax:
-
-.. code-block:: jinja
-
- {{ '{{' }}
-
-For larger blocks that contain Jinja syntax that needs to be escaped, you can use
-raw blocks:
-
-.. code-block:: jinja
-
- {% raw %]
- some text that contains jinja characters that need to be escaped
- {% endraw %}
-
-See the `Escaping`_ section of Jinja's documentation to learn more.
-
-A real-word example of needing to use raw tags to escape a larger block of code
-is when using ``file.managed`` with the ``contents_pillar`` option to manage
-files that contain something like consul-template, which shares a syntax subset
-with Jinja. Raw blocks are necessary here because the Jinja in the pillar would
-be rendered before the file.managed is ever called, so the Jinja syntax must be
-escaped:
-
-.. code-block:: jinja
-
- {% raw %}
- - contents_pillar: |
- job "example-job" {
-
- task "example" {
- driver = "docker"
-
- config {
- image = "docker-registry.service.consul:5000/example-job:{{key "nomad/jobs/example-job/version"}}"
-
- {% endraw %}
-
-.. _`Escaping`: http://jinja.pocoo.org/docs/dev/templates/#escaping
-
-Calling Salt Functions
-======================
-
-The Jinja renderer provides a shorthand lookup syntax for the ``salt``
-dictionary of :term:`execution function `.
-
-.. versionadded:: 2014.7.0
-
-.. code-block:: yaml
-
- # The following two function calls are equivalent.
- {{ salt['cmd.run']('whoami') }}
- {{ salt.cmd.run('whoami') }}
-
-Debugging
-=========
-
-The ``show_full_context`` function can be used to output all variables present
-in the current Jinja context.
-
-.. versionadded:: 2014.7.0
-
-.. code-block:: yaml
-
- Context is: {{ show_full_context() }}
+For Jinja usage information see :ref:`Understanding Jinja `.
'''
# Import python libs
diff --git a/salt/renderers/yaml.py b/salt/renderers/yaml.py
index 9d8fa83c89b8..ca506cbb699a 100644
--- a/salt/renderers/yaml.py
+++ b/salt/renderers/yaml.py
@@ -1,6 +1,8 @@
# -*- coding: utf-8 -*-
'''
YAML Renderer for Salt
+
+For YAML usage information see :ref:`Understanding YAML `.
'''
from __future__ import absolute_import