The snapshot_prep Script

Valid for versions 120 through the latest version

Version:

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:

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=package1,package2` Note: In this example, `package1` and `package2` represent the packages you wish to install.
`--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.