About file sync

This version is out of date. For current versions, see Puppet Enterprise support lifecycle.

File sync keeps your Puppet code synchronized across multiple masters. When triggered by a web endpoint, file sync takes changes from your working directory on your master of masters (MoM) and deploys the code to a live code directory. File sync then automatically deploys that code onto all your compile masters, ensuring that all masters in a multi-master configuration are kept in sync.

In addition, file sync ensures that your Puppet code is deployed only when it is ready. Atomic deployments ensure that your Puppet agents’ code won’t change during a run. File sync also triggers an environment cache flush when the deployment has finished, to ensure that new agent runs happen against the newly deployed Puppet code.

File sync works with Code Manager, so you typically won’t need to do anything with file sync directly. If you want to know more about how file sync works, or you need to work with file sync directly for testing, this page provides additional information.

Terms to know

Master of masters (or MoM): This is your “main” Puppet master. It typically serves as the Certificate Authority for all of your other masters, as well as for all of your agent nodes. In the context of file sync, it is also responsible for maintaining the canonical copy of all of your Puppet code and making it available to compile masters.

Compile master: These are secondary masters, generally added to your infrastructure as needed to scale up to the amount of load generated by your fleet of Puppet agents. They are typically set up behind a load balancer. In the context of file sync, these masters acquire the latest version of your Puppet code from the master of masters.

Live code directory: This is the directory that all of the Puppet environments, manifests, and modules are stored in. This directory is used by Puppet Server for catalog compilation. It corresponds to Puppet Server’s master-code-dir setting and Puppet’s $codedir setting. The default value is /etc/puppetlabs/code. In file sync configuration, you may see this referred to simply as live-dir. This directory exists on all of your masters.

Staging code directory: This is the directory in which you should stage your code changes before rolling them out to the live code dir. Files can be moved into this directory however you normally do so. Then, when you trigger a file sync deployment, file sync moves the changes to the live code dir on all of your masters. This directory exists only on the master of masters; the compile masters do not need a staging directory. The default value is /etc/puppetlabs/code-staging.

How file sync works

By default, file sync is disabled and the staging directory is not created on the MoM. If you’re upgrading from 2015.2 or earlier, file sync is disabled after the upgrade. You must enable file sync, and then run Puppet on all masters. This creates the staging directory on the MoM, which you can then populate with your Puppet code. File sync can then commit your code; that is, it can prepare the code for synchronization to the live code directory, and then your compile masters. Normally, Code Manager triggers this commit automatically, but you can trigger a commit by hitting the file sync endpoint.

For example:

/opt/puppetlabs/puppet/bin/curl -s --request POST --header "Content-Type: application/json" --data '{"commit-all": true}' --cert ${cert} --key ${key} --cacert ${cacert} https://${fqdn}:8140/file-sync/v1/commit"

The above command is run from the MoM and contains the following variables:

  • fqdn: Fully qualified domain name of the MoM.
  • cacert: The Puppet CA’s certificate (/etc/puppetlabs/puppet/ssl/certs/ca.pem).
  • cert: The ssl cert for the MoM (/etc/puppetlabs/ssl/certs/${fqdn}.pem).
  • key: The private key for the MoM (/etc/puppetlabs/ssl/private_keys/${fqdn}.pem).

This command commits all of the changes in the staging directory. After the commit, when any compile masters check the file sync service for changes, they receive the new code and deploy it into their own code directories, where it is available for agents checking in to those masters. (By default, compile masters check file sync every 5 seconds.)

Commits can be restricted to a specific environment and can include details such as a message, and information about the commit author. For more details, please see the API docs.

Enabling or disabling file sync

File sync’s behavior is linked to that of Code Manager. Because Code Manager is disabled by default, file sync is also disabled. To enable file sync, enable Code Manager. You can enable and configure Code Manager either during or after PE installation.

The file_sync_enabled parameter in the puppet_enterprise::profile::master class in the PE console defaults to ‘automatic,’ which means that file sync is enabled and disabled automatically with Code Manager. If you set this parameter to true, it forces file sync to be enabled even if Code Manager is disabled. The file_sync_enabled parameter doesn’t appear in the class definitions — you must add the parameter to the class in order to set it.

Checking your deployments

You can manually check information about file sync’s deployments with curl commands that hit the status endpoint.

  • To manually check that your code has been successfully committed and deployed, you can hit a status endpoint on the MoM. For example:

    curl -k https://${fqdn}:8140/status/v1/services?level=debug

    This returns output in JSON, so you can pipe it to python -m json.tool for better readability.

  • To check a list of file sync’s clients, query the file-sync-storage-service section of the MoM by running this curl command:

    curl -k https://${fqdn}:8140/status/v1/services/file-sync-client-service?level=debug

    This command returns a list of:

    • All of the clients that file sync is aware of.
    • When those clients last checked in.
    • Which commit they have deployed .

If your commit has been deployed, it is listed in the status listing for latest_commit. More detail about the status endpoint is available in the API docs.


Always use the staging directory

Always make changes to your Puppet code in the staging directory. If you have edited code in the live code directory on the MoM or any compiled masters, it will be overwritten by file sync on the next commit.

The enable-forceful-sync parameter is set to true by default in PE. When false, file sync will not overwrite changes in the code directory, but instead logs errors in /var/log/puppetlabs/puppetserver/puppetserver.log. To set this parameter to false, add via Hiera (puppet_enterprise::master::file_sync::file_sync_enable_forceful_sync: false).

Puppet module command and file sync

The puppet module command doesn’t work correctly with file sync enabled. If you need modules, specify them in the Puppetfile and use Code Manager to handle your syncs.


File sync runs as the pe-puppet user. To sync files, file sync must have permission to read the staging directory and to write to all files and directories in the live code directory. To make sure file sync can read and write what it needs to, ensure that these code directories are both owned by the pe-puppet user:

chown -R pe-puppet /etc/puppetlabs/code /etc/puppetlabs/code-staging

Environment isolation metadata

File sync generates .pp metadata files in both your live and staging code directories. These files provide environment isolation for your resource types, ensuring that each environment uses the correct version of the resource type. Do not delete or modify these files. Do not use expressions from these files in regular manifests.

For more details about these files and how they isolate resource types in multiple environments, see environment isolation.

See an issue? Please file a JIRA ticket in our [DOCUMENTATION] project
Puppet sites use proprietary and third-party cookies. By using our sites, you agree to our cookie policy.