Docs Puppet Enterprise Maintenance Backing up and restoring Puppet Enterprise

Backing up and restoring Puppet Enterprise

Sections

Keep regular backups of your PE infrastructure. Backups allow you to more easily migrate to a new primary server, troubleshoot, and quickly recover in the case of system failures.

Note: These instructions are intended only for standard installations without disaster recovery.

Important: Store your backups in a secure, centralized location that you can access if your primary server fails.

You can use the puppet-backup command to back up and restore your primary server. You can't use this command to back up compilers. By default, the backup command creates a backup of:

Your PE configuration, including license, classification, and RBAC settings. However, configuration backup does not include Puppet gems or Puppet Server gems.
PE CA certificates and the full SSL directory.
The Puppet code deployed to your code directory at backup time.
PuppetDB data, including facts, catalogs and historical reports.

Each time you create a new backup, PE creates a single, timestamped backup file, named in the format pe_backup-<TIMESTAMP>.tgz. This file includes everything you're backing up. By default, PE writes backup files to /var/puppetlabs/backups, but you can change this location when you run the backup command. When you restore, specify the backup file you want to restore from.

If you are restoring to a previously existing primary server, uninstall and reinstall PE first. If you are restoring or migrating to a primary server with a different hostname, you can redirect your agents to the new primary server during the restore process. In both cases, you must restore to the same PE version used to create your backups. If your installation includes disaster recovery, you must complete the restore process before reprovisioning a new replica.

Customizing backup and restore scope

By default, backup and restore functions include your Puppet configuration, certificates, code, and PuppetDB. However, you can limit the scope of backup and restore with command line options. This allows you to back up to or restore from multiple files. This is useful if you want to back up some parts of your infrastructure more often than others.

For example, if you have frequent code changes, you might back up the code more often than you back up the rest of your infrastructure. When you limit backup scope, the backup file contains only the specified parts of your infrastructure. Be sure to give your backup file a name that identifies the scope so that you always know what a given file contains.

During restore, you must restore all scopes: code, configuration, certificates, and PuppetDB. However, you can restore each scope from different files, either by restoring from backup files with limited scope or by limiting the scope of the restore. For example, by specifying scope when you run the restore command, you could restore code, configuration, and certificates from one backup file and PuppetDB from a different one.

Back up your infrastructure

PE backup creates a copy of your primary server, including configuration, certificates, code, and PuppetDB. Backup can take up to several hours depending on the size of PuppetDB.

Before you begin

To optionally encrypt your backup, you must import your GPG public key to your primary server.

Note: Ensure pg_repack won't run prior to or during the backup/restore process.

By default, PE backs up files to /var/puppetlabs/backups.

On your primary server logged in as root, run puppet-backup create --dir=<BACKUP_DIRECTORY>, specifying a separate disk as your backup directory.
You can specify these optional parameters:
- --name=<BACKUP_NAME> – Specifies a name for the backup file. Default: pe_backup-<TIMESTAMP>.tgz
- --pe-environment=<ENVIRONMENT> – Specifies an environment to back up. To ensure configuration is recovered correctly, this must be the environment where your primary server is located. Default: production
- --scope=<SCOPE_LIST> – Specifies the data to back up: certs, code, config, puppetdb. Default: all
- --gpgkey=<KEY_ID> – Specifies a GPG key ID to use for encrypting the backup file.
- --force – Bypasses validation checks and ignore warnings.
Back up the secret keys directory and, if enabled, the secret key for the LDAP service.
- Secret keys directory location: /etc/puppetlabs/orchestration-services/conf.d/secrets/
- LDAP service key location: /etc/puppetlabs/console-services/conf.d/secrets/keys.json
Secure the keys as you would any sensitive information.

CAUTION: The backup command does not include secret keys. You must back up this information separately.

Restore your infrastructure

Use the restore commands to migrate your primary server to a new host or to recover from system failure.

Before you begin

To decrypt an encrypted backup, you must import the GPG key pair (public and private keys) used for encryption to your new primary server.

Note: Ensure pg_repack won't run prior to or during the backup/restore process.

If you are restoring to an existing primary server, purge any existing PE installation.
1. On your primary server, uninstall PE by running sudo /opt/puppetlabs/bin/puppet-enterprise-uninstaller -p -d
2. Ensure that the directories /opt/puppetlabs/ and /etc/puppetlabs/ are no longer present on the system.
Install PE on the primary server you are restoring to. This must be the same PE version used to create the backup files.
1. If you don't have the PE installer script on the machine you want to restore to, download the installer tarball to the machine from the download site, and unpack it by running tar -xf <TARBALL_FILENAME>
2. Navigate to the directory containing the install script. The installer script is located in the PE directory created when you unpacked the tarball.
3. Install PE by running sudo ./puppet-enterprise-installer
On your primary server logged in as root, restore your PE infrastructure by running puppet-backup restore <BACKUP-FILENAME>
You can specify these optional parameters:
- --pe-environment=<ENVIRONMENT> – Specifies an environment to restore. Default: production
- --scope=<SCOPE_LIST> – Specifies the data to restore: certs, code, config, puppetdb. Default: all
- --force – Bypasses validation checks and ignore warnings.
Restore your backup of the secret keys used to encrypt and decrypt sensitive data stored in the inventory service, orchestrator, and, if enabled, the LDAP service.
- Inventory service and orchestrator keys directory location: /etc/puppetlabs/orchestration-services/conf.d/secrets/
- LDAP service key location: /etc/puppetlabs/console-services/conf.d/secrets/keys.json
CAUTION: The restore command does not include secret keys. You must restore this information separately.
Ensure the secret key ownership for the inventory and LDAP services are as follows:
- Inventory: pe-orchestration-services:pe-orchestration-services
- LDAP: pe-console-services:pe-console-services
Restart pe-orchestration-services and pe-console-services
If you restored PE onto a primary server with a different hostname than the original installation, and you have not configured the dns_alt_names setting in the pe.conf file, redirect your agents to the new primary server. An easy way to do this is by running a task with the Bolt task runner.
1. Download and install Bolt , if you don't already have it installed.
2. Update the puppet.conf file to point all agents at the new primary server by running:
```
bolt task run puppet_conf action=set section=agent setting=server value=<RESTORE_HOSTNAME> --targets <COMMA-SEPARATED LIST OF NODES>
bolt task run puppet_conf action=set section=main setting=server value=<RESTORE_HOSTNAME> --targets <COMMA-SEPARATED LIST OF NODES>Copied!
```
3. Run puppet agent -t --no-use_cached_catalog on the newly restored primary server twice to apply changes and then restart services.
4. Run puppet agent -t --no-use_cached_catalog on all agent nodes to test connection to the new primary server.
If your infrastructure had Code Manager enabled when your backup file was created, deploy your code by running:
```
puppet-access login
puppet code deploy --all --waitCopied!
```
If your installation includes disaster recovery, reprovision a new replica.

Directories and data backed up

These are the directories and data included in PE backups.


Scope	Directories and databases backed up
`certs`	`/etc/puppetlabs/puppet/ssl/`
`code`	`/etc/puppetlabs/code/` `/etc/puppetlabs/code-staging/` `/opt/puppetlabs/server/data/puppetserver/filesync/storage/`
`config`	Orchestrator database RBAC database Classifier database `/etc/puppetlabs/` , except: `/etc/puppetlabs/code/` `/etc/puppetlabs/code-staging/` `/etc/puppetlabs/puppet/ssl` `/opt/puppetlabs/` , except: `/opt/puppetlabs/puppet` `/opt/puppetlabs/server/pe_build` `/opt/puppetlabs/server/data/packages` `/opt/puppetlabs/server/apps` `/opt/puppetlabs/server/data/postgresql` `/opt/puppetlabs/server/data/enterprise/modules` `/opt/puppetlabs/server/data/puppetserver/vendored-jruby-gems` `/opt/puppetlabs/bin` `/opt/puppetlabs/client-tools` `/opt/puppetlabs/server/share` `/opt/puppetlabs/server/data/puppetserver/filesync/storage` `/opt/puppetlabs/server/data/puppetserver/filesync/client`
`puppetdb`	PuppetDB `/opt/puppetlabs/server/data/puppetdb` Note: The `stockpile` directory is excluded from backup.