Last modified: 2026 February 9

Overview

The /usr/local/cpanel/scripts/snapshot_prep script prepares your server to create a deployment image.

This script does not support all server configurations. The script checks your server for some, but not all, unsupported configurations. The script will exit early if any of the following exist on your server:

• API Tokens.
• A backup of the server, or a directory for backups.
• Two-factor authentication enabled for the root user.
• Links to another server through a cluster or a linked node.
• One or more configured contacts in /etc/wwwacct.conf or /etc/wwwacct.conf.shadow.
• A remote MySQL® profile set up in WHM’s Manage Database Profiles interface (WHM » Database Services » Manage Database Profiles).

This is not an exhaustive list of unsupported configurations, and we do not maintain a list of unsupported configurations. For more information about setting up virtualization templates, read our Best Practices for cPanel Virtualization Templates documentation.

Run the script

To run this script on the command line, use the following format:

/usr/local/cpanel/scripts/snapshot_prep [options]

Options

Use the following options with this script:

Create a third-party plugin

If you maintain third-party software for cPanel & WHM servers, you can provide a plugin for your users to run with the snapshot_prep script. By using your plugin, users can run additional tasks when preparing their servers to create deployment images. For example, imagine your software includes a unique access token. You want each instance created from an image to have its own unique token. In this case, we recommend creating a third-party plugin that adds a task to perform the following:

• Clean the token when a user runs the snapshot_prep script so that the token is not included in the image.

• Generate a new token upon the first boot of instances created from the image.

The snapshot_prep script uses .json files to point to a third-party plugin script. Before a plugin can run, your software must install a .json file in the /var/cpanel/snapshot_prep.d directory on your user’s server.

The .json file must use the following format:

1
2
3
4
5
6
7

{
  "name": "exampleplugin",
  "type": "non-repair only",
  "pre": ["/var/cpanel/exampleplugin.py", "--before"],
  "post": ["/var/cpanel/exampleplugin.py", "--after"],
  "description": "Perform a task.\n"
}

The .json file includes the following options:

Dependencies for third-party plugins

This system allows third-party plugins to customize or replace the default dependencies. Third-party plugins in this system can define their own dependencies using the deps key in the plugin’s .json file.

If you do not specify dependencies, the system uses the following tasks as the default dependencies for all third-party plugins:

• ipaddr_and_hostname
• mysql
• cpwhm_misc

For a description of these tasks, as well as all other tasks in this script, use the --list-tasks option.

You can override these default dependencies by specifying a deps key in the plugin’s .json file. The deps key should contain a list of one or more tasks that must run before this plugin. For example:

1
2
3
4
5
6
7
8
9

{
  "name": "exampleplugin",
  "type": "non-repair only",
  "pre": ["/var/cpanel/exampleplugin.py", "--before"],
  "post": ["/var/cpanel/exampleplugin.py", "--after"],
  "description": "Perform a task.\n",
  "deps": ["mysql"],
  "before": ["other_task"]
}