.. -*- mode: rst -*-

.. _server-caching:

===================
Server-side Caching
===================

Metadata Caching
================

.. versionadded:: 1.3.0

Caching (or, rather, cache expiration) is always a difficult problem,
but it's particularly vexing in Bcfg2 due to the number of different
data sources incorporated.  In 1.3.0, we introduce some limited
caching of client metadata objects.  Since a client metadata object
can be generated anywhere from 7 to dozens of times per client run
(depending on your templates), and since client metadata generation
was made more complex and powerful in 1.3.0, caching these objects
provides the easiest performance gain.

To enable caching, add a ``[caching]`` section to bcfg2.conf with a
client_metadata option containing one of the following modes:

* ``off``: No caching of client metadata objects is performed.  This
  is the default.
* ``initial``: Only initial metadata objects are cached.  Initial
  metadata objects are created only from the data in the
  :ref:`server-plugins-grouping-metadata` plugin, before additional
  groups from other plugins are merged in.
* ``cautious``: Final metadata objects are cached, but each client's
  cache is cleared at the start of each client run, immediately after
  probe data is received.  Cache is also cleared as in ``aggressive``
  mode.  ``on`` is a synonym for ``cautious``.
* ``aggressive``: Final metadata objects are cached.  Each plugin is
  responsible for clearing cache when appropriate.

These are presented roughly in ascending order of speed, and
descending order of reliability.  That is, odds are higher that
``aggressive`` mode will result in stale data, but it gives the
biggest speed boost.  ``off`` will never result in stale data, but it
gives no speed boost.

In addition to the :ref:`server-plugins-grouping-metadata` plugin,
Bcfg2 includes three plugins that can set additional groups, and thus
may affect the caching behavior.  They are
:ref:`server-plugins-grouping-grouppatterns`,
:ref:`server-plugins-probes-index`, and
:ref:`server-plugins-connectors-puppetenc`.  All of those plugins
**except** for PuppetENC fully support all caching levels.  PuppetENC
is incompatible with ``aggressive``, and may result in some stale data
with ``cautious``.

If you are not using the PuppetENC plugin, and do not have any custom
plugins that provide additional groups, then all four modes should be
safe to use.  If you are using PuppetENC or have custom Connector
plugins that provide additional groups, then you may want to start
with ``cautious`` or ``initial``.
