Cache directory (vardir)

As part of its normal operations, Puppet generates data which is stored in a cache directory called vardir. You can mine the data in vardir for analysis, or use it to integrate other tools with Puppet.

Location

The cache directory for Puppet Server defaults to /opt/puppetlabs/server/data/puppetserver.

The cache directory for the Puppet agent and Puppet apply can be found at one of the following locations:

  • *nix systems: /opt/puppetlabs/puppet/cache.

  • Non-root users: ~/.puppetlabs/opt/puppet/cache.

  • Windows: %PROGRAMDATA%\PuppetLabs\puppet\cache (usually C:\Program Data\PuppetLabs\puppet\cache).

When Puppet is running as root, a Windows user with administrator privileges, or the puppet user, uses a system-wide cache directory. When running as a non-root user, it uses a cache directory in the user’s home directory.

Because you usually run Puppet’s commands and services as root or puppet, the system cache directory is what you usually want to use.

Important: To use the same directories as the agent or primary server, admin commands like puppetserver ca, must run with sudo.
Note: When the primary server is running as a Rack application, the config.ru file must explicitly set --vardir to the system cache directory. The example config.ru file provided with the Puppet source does this.

You can specify Puppet’s cache directory on the command line by using the --vardir option, but you can’t set it in puppet.conf. If --vardir isn’t specified when a Puppet application is started, it uses the default cache directory location.

To configure the Puppet Server cache directory, use the jruby-puppet.server-var-dir setting in puppetserver.conf .

Interpolation of $vardir

The value of the vardir is discovered before other settings, so you can reference it using the $vardir variable in the value of any other setting in puppet.conf or on the command line.

For example: 
[main]
  ssldir = $vardir/ssl

If you need to set nonstandard values for some settings, using the $vardir variable allows you to avoid absolute paths and keep your Puppet-related files together.

Contents

The vardir contains several subdirectories. Most of these subdirectories contain a variable amount of generated data, some contain notable individual files, and some directories are used only by agent or primary server processes.

To change the locations of specific vardir files and directories, edit the settings in puppet.conf. For more information about each item below, see the Configuration reference.
Directory name Config setting Notes
bucket bucketdir
client_data client_datadir
clientbucket clientbucketdir
client_yaml clientyamldir
devices devicedir
lib/facter factpath
facts factpath
facts.d pluginfactdest
lib libdir, plugindest Puppet uses this as a cache for plugins (custom facts, types and providers, functions) synced from a primary server. Do not change its contents. If you delete it, the plugins are restored on the next Puppet run.
puppet-module module_working_dir
puppet-module/skeleton module_skeleton_dir
reports reportdir When the option to store reports is enabled, a primary server stores reports received from agents as YAML files in this directory. You can mine these reports for analysis.
server_data serverdatadir
state statedir See table below for more details about the state directory contents.
yaml yamldir
The state directory contains the following files and directories:
File or directory name Config setting Notes
agent_catalog_run.lock agent_catalog_run_lockfile
agent_disabled.lock agent_disabled_lockfile
classes.txt classfile This file is useful for external integration. It lists all of the classes assigned to this agent node.
graphs directory graphdir When graphing is enabled, agent nodes write a set of .dot graph files to this directory. Use these graphs to diagnose problems with the catalog application, or visualizing the configuration catalog.
last_run_summary.yaml lastrunfile

This file is stored in a public directory and is visible to external monitoring tools — making sure the Puppet agent is running every 30 minutes.
last_run_report.yaml lastrunreport
resources.txt resourcefile
state.yaml statefile