.. -*- mode: rst -*- .. vim: ft=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 introduced 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`, 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``.