1. cPanel & WHM Documentation
  2. WHM
  3. Scripts
  4. The snapshot_prep Script
whmadvanced images

The snapshot_prep Script

Valid for versions 106 through 118

Version:

106

120

Last modified: March 27, 2024

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:

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:

Option Description
Example
--no-post-service Do not install the on-first-boot service. You must manually run the post_snapshot script on the first boot of an instance created from an image. --no-post-service
--list-tasks Return a list of tasks that the script will perform. --list-tasks
--skip A comma-delimited list of tasks to skip.
Note:
  • We strongly recommend that you do not use the --skip option. Skipping tasks can cause unpredictable behavior on your server.
  • You cannot combine the --skip and --only options.
 --skip=mysql,license
--only A comma-delimited list of tasks to perform, skipping all other tasks.
Note:
  • We strongly recommend that you do not use the --only option. Skipping tasks can cause unpredictable behavior on your server.
  • You cannot combine the --skip and --only options.
 --only=license
--instance-packages Include a comma-delimited list of packages to install on the first boot of instances created from an image. Use this option for packages that generate per-instance data during installation. When you use this option, you avoid saving per-instance data to your deployment image. --instance-packages=cpanel-ccs-calendarserver,cpanel-z-push
--delete-saved-copies Delete backup copies of configuration files. The snapshot_prep script automatically saves these copies to your server. If you do not delete the copies, they will also exist on any images created from the server. --delete-saved-copies
--help Display the script’s help documentation. --help

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.

Important:

cPanel & WHM does not create third-party plugins for the snapshot_prep script.

This script uses a dependency system. The following tasks are dependencies for all third-party plugins. You cannot remove these dependencies:

  • 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.

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:

Item Description
name The name of the file, excluding the .json suffix. For example, if the file is named example.json, write example in the name field.
Note:

The file name can only include letters, numbers, and underscores.
type The type must be non-repair only.
pre An executable file and any additional arguments.
post An executable file and any additional arguments.
description A description of what the plugin does.

Additional Documentation