About file sync

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.

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 and prepare to synchronize it with your compile masters.

For example, the following curl command triggers a commit; that is, file sync prepares the code for synchronization to the live code directory:

/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 the variables are the following:

  • 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 new changes (by default every 5 seconds), they receive the new code and deploy it into their own code dir, where it is available for agents checking in to those masters.

Commits can also 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

In the PE console, you can enable or disable file sync in the puppet_enterprise::profile::master class’s file_sync_enabled parameter. This parameter’s value defaults to ‘automatic’ on fresh installations and upgrades, and as such doesn’t appear in the class definitions — you must add the parameter to the class in order to set it. The ‘automatic’ value links file sync’s behavior to Code Manager’s, and Code Manager is disabled by default, so file sync is as well. If Code Manager is enabled, file sync is enabled as well.

To disable file sync, set this parameter to false. If you set this parameter to false and set code_manager_auto_configure to true, Code Manager deploys directly to your live code directory (/etc/puppetlabs/code). This configuration is neither recommended nor supported.

To enable file sync, we recommend enabling and using Code Manager. To force file sync to be enabled even when Code Manager is disabled, set this parameter’s value to true. If upgrading from a previous version, also follow the documentation for configuring Code Manager after installation.

Checking your deployments

To make sure that your code has been successfully committed and deployed, you can hit a status endpoint on the MoM:

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

This returns output in JSON, so piping it to python -m json.tool might be helpful.

On the MoM, there is a section called file-sync-storage-service that has a listing of all of the clients it knows about, when they last checked in, and which commit they have deployed. To query just this section, run:

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

If your commit has been deployed, you will see it 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. To set this parameter to false, add via hiera (puppet_enterprise::master::file_sync::file_sync_enable_forceful_sync: false). When false, file sync will not overwrite changes in codedir, but will instead log errors in /var/log/puppetlabs/puppetserver/puppetserver.log.

Puppet module command and file sync

The puppet module command doesn’t work well with file sync. 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, so in order to sync files in the staging dir, it needs to be able to read them. In order to sync files and directories to the live code directory, file sync must be able to write to the live code directory and all files and directories in it. To make sure file sync can read and write what it needs to, ensure that the live code directory is owned by pe-puppet:

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.

↑ Back to top