The snapshot_prep Script

Valid for versions 106 through the latest version

Version:

106


Last modified: June 24, 2022

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.

The snapshot_prep script uses .json files to point to a third-party plugin script. The .json files 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 options in this .json file include:

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