Performing actions Before and After the backup task

This documentation is for an older version of CCC. You can find the latest version here.
Last updated on 7. August 2020

Often when you have a backup task that runs on a scheduled basis, there are associated tasks that you would like to perform before or after files are actually copied. CCC offers the option to run shell scripts before and after a backup task, unmount or set the destination as the startup disk, run another CCC backup task, and power management options such as restart and shutdown. If you would like to perform any of these pre or post clone tasks, click the Advanced Settings button below CCC's Source selector.

Mounting the source or destination volume before a backup task begins

Without any additional configuration, CCC will attempt to mount your source and destination volumes before a backup task begins. This applies to many different volume types — ordinary volumes on locally-attached hard drives, disk images, network volumes, encrypted volumes – even encrypted volumes on remote Macs. If your source or destination volume is on a disk that is physically attached to your Mac (e.g. via Thunderbolt or USB), but it is not mounted, CCC can "see" that device and will attempt to mount it. If your source or destination is a network volume, CCC will obtain the credentials that you use to mount that device when you create the backup task, and will use those credentials to mount the volume before the task begins.

This also applies for nested volumes. For example, suppose you are backing up to a disk image on a network volume. CCC will first attempt to mount the network volume, then it will attempt to mount the disk image. Likewise, suppose you have a task configured to back up the contents of a folder on an encrypted volume. If you have saved the encrypted volume's passphrase in CCC's keychain, CCC will unlock and mount the encrypted volume before the backup task begins.

CCC's attempts to mount the source and destination volumes occur automatically before any other tasks, including pre clone shell scripts (described below), therefore it is not necessary to implement a shell script to pre-mount the source or destination.

Little Snitch may prevent the automated mounting of network volumes

If you're using Little Snitch to monitor and filter your inbound and outbound network traffic, you may find that CCC has trouble automatically mounting a network volume. If you run into this problem, configure Little Snitch to allow network access to the NetAuthSysAgent system service. NetAuthSysAgent is the macOS system service that fulfills application requests to mount network volumes.

SafetyNet Pruning

SafetyNet pruning is covered in more detail in this section of CCC's documentation.

Destination volume options

If you would like CCC to unmount your destination volume at the end of the backup task, choose Unmount the destination volume from the Destination volume management menu. If your destination is a folder, the text will be Unmount the underlying volume. If the destination is a disk image, CCC always unmounts the disk image volume, so this setting refers to the underlying physical volume upon which the disk image resides.

CCC will not forcefully unmount the destination volume. If an application has open files on the destination volume, CCC's attempt to unmount the volume will fail. CCC does not report this as an error, though it will make a note of it in the Task History window.

Yosemite users have an option to set the destination volume as the startup disk. Starting in El Capitan, however, Apple's System Integrity Protection prevents third-party applications from changing the startup disk setting. We do not recommend disabling System Integrity Protection to make this feature work, rather we recommend that you use the Startup Disk Preference Pane to change the startup disk selection.

Power management options

By default, at the end of a backup task, CCC will not perform any power management tasks. Instead, the system will perform as defined by the settings in the Energy Saver preference pane. For example, if you have the system configured to idle sleep after 20 minutes, the system will go to sleep if there hasn't been any user activity in the last 20 minutes. CCC activity is not considered user activity, so often the system will go to sleep immediately after CCC finishes a backup task.

If you choose one of the options from the Power management menu, CCC will reboot or shut down your Mac when the backup task finishes. The reboot and shutdown options are not forceful. If you have a document open with unsaved modifications, for example, the application would prompt you to save the document. If a save dialog is not attended to, the shutdown or reboot request will time out.

Turn off the computer if it was previously off

If your backup task is scheduled to run on a regular basis, this option will be enabled in the Power Management popup menu. This option is applicable if you would like to have CCC shut down your Mac at the end of the task, but only in cases where the Mac was booted at the task's scheduled run time. If your backup task runs when the system has been on for a while or has been sleeping, CCC will not shut down the Mac when using this option.

Power Management options are ignored in some cases

Power management options will not be applied to backup tasks that are cancelled (e.g. you click the Stop button). Additionally, power management tasks will not be applied if other CCC backup tasks are running or queued to run immediately after the current task finishes running. If your task is running as part of a Task Group, power management options will be deferred to when all tasks within the group have completed.

Power Management options are applied regardless of task success

Power management options will be applied whether the backup task completes successfully or not. If you prefer for a backup task to perform the power management action only when the backup task exits without error, see the pm_on_success.sh postflight script below.

Run another backup task (task chaining)

If you have more than one CCC backup task configured, the other tasks will be listed in this popup menu. To create a task chain (e.g. to run tasks sequentially), simply choose one of these tasks to have that task run automatically after the current task finishes. Tasks run in this manner will start after the current task has finished completely. Chained tasks will run regardless of the exit status of a preceding task in the chain, e.g. if the first task reports errors or fails to run at all, the second task will still run. Only the first task in a chain needs to be scheduled to start the chain.

Note: Postflight tasks will not be started if the current task was started via a task group. When you run a task group, we're specifically aiming to run exactly the tasks within that task group, and within the order specified. If you run the task manually, however, or if the task is run separately from the group on its own schedule, then the task's postflight task will be run.

Running shell scripts before and after the backup task

If there is functionality that you need that does not exist within CCC, pre and post clone shell scripts may be the solution for you. Pre clone shell scripts run after CCC has performed "sanity" checks (e.g. are the source and destination volumes present, is connectivity to a remote Macintosh established) but before copying files. If you need your preflight script to run before CCC does the source/destination sanity checks, specify the preflight script as a global preflight script in the Advanced section of CCC's Preferences window. Note that global preflight scripts run prior to every task, they are not task-specific. Also, please bear in mind that CCC automatically attempts to mount the source and destination at the beginning of the task, you should not be implementing a shell script to achieve that functionality. If you're having trouble with CCC pre-mounting the source and destination, please ask us for help rather than attempt to address the issue with a preflight shell script.

Post-clone shell scripts run after CCC has finished copying files and performing its own internal cleanup, but before unmounting any volumes.

CCC passes several parameters to pre and post clone shell scripts. For example, the following shell script:

#!/bin/sh

echo "Running $0"
echo `date`
echo "Source: $1"
echo "Destination: $2"
echo "Third argument: $3" # Exit status for post-clone scripts, underlying volume path for a disk image for pre-clone scripts
echo "Fourth argument: $4" # Destination disk image path, if applicable

 

Would produce the following output (you can redirect this output to a file of your own specification) if implemented as a post clone script:

 

Running /Library/Application Support/com.bombich.ccc/Scripts/postaction.sh
Wed Oct 8 21:55:28 EDT 2014
Source: /
Destination: /Volumes/Offsite Backup
Third argument: 0
Fourth argument:

First parameter

The path to the source volume or folder. If the source volume is APFS-formatted, then this path will usually be the path to a temporary, read-only snapshot of the source (or the path to the source folder on the temporary, read-only snapshot). On macOS Catalina and later, if the source volume is a System volume, CCC will send the path to a snapshot of the Data sibling of the source as the first parameter.

Second parameter

The path to the destination volume or folder. If the destination is a disk image, this is the path to the mounted disk image. On macOS Catalina and later, if the destination volume is a System volume, CCC will send the path to the Data sibling of the destination as the second parameter, e.g. "/Volumes/Clone - Data".

Third parameter

  • Pre clone script: The underlying mountpoint for the volume that holds the destination disk image, if applicable.
  • Post clone script: The exit status of the file copying phase of the backup task.

Fourth parameter

The path to the destination disk image, if applicable.

If your pre clone script exits with a non-zero exit status, it will cause CCC to abort the backup task. This can be used to your advantage if you want to apply preconditions to your backup operation. If you want to be certain that errors in your pre clone shell script never cause the backup task to be aborted, add "exit 0" to the end of your script. If you would like that script to silently cancel the backup task, add "exit 89" to the end of the script. If the script is a global preflight script (specified in the Advanced section of CCC's Preferences window), you can add "exit 104" to the end of the script to cancel the backup task and to avoid recording a Task History event.

The post clone script will run whether the backup task exits successfully or not. If your script should behave differently depending on the result of the task, you can test whether the third parameter is zero (an exit status of "0" means the task ended successfully). For example:

#!/bin/sh

source="$1"
dest="$2"
exitStatus=$3

if [ "$exitStatus" = "0" ]; then
    # task succeeded
else
    # task failed or reported errors
    # Note: Do not assume that $source and $dest are populated
    # These will be empty if source or destination validation fails
fi

If your postflight script exits with a non-zero exit status, CCC will not report this as a failure of the backup task. The failure will be noted in the Task History window, however.

AppleScripts are not supported

You cannot specify an AppleScript as a pre or post clone script, CCC currently only supports running shell scripts.

Shell scripts require a shell interpreter line

CCC does not assume a default shell environment when running your pre or postflight script. Not doing so gives users a great deal of flexibility; they can choose to write their scripts in any shell or programming language (e.g. bash, python, perl, ruby, C). For CCC to execute a shell script as an application, though, the system needs to know what shell should be used to interpret the script, and that value needs to be defined in your shell script. This is done simply by placing a shell interpreter line at the top of the file, e.g. #!/bin/sh.

Shell scripts run as the root user

CCC's pre and post clone shell scripts are executed as the System Administrator (aka "root"). As such, any references to your own shell environment will be invalid. When referencing tools that lie outside of the default $PATH, be sure to either specify the full path to the item (e.g. /usr/local/bin/foo), or export your own $PATH at the top of your script. Likewise, if you make relative references to files (e.g. ~/Desktop/foo.log), those files will be created in the root user account, e.g. /var/root/Desktop/foo.log. Use absolute paths for more reliable results.

Security implications of pre and post clone shell scripts

To prevent unauthorized modifications to your shell scripts, we recommend that you restrict the ownership and permissions of these scripts and to the folder in which they are contained. The parent folder and scripts should be writable only by the root user. For example, running the following in the Terminal application would secure any shell scripts located in the default location for pre and post clone scripts:

sudo chown -R root:wheel /Library/Application\ Support/com.bombich.ccc/Scripts
sudo chmod -R 755 /Library/Application\ Support/com.bombich.ccc/Scripts

To further enhance the security of your pre and postflight scripts, CCC will require that scripts stored in the default location are owned by the root user and writable only by the root user, and that the Scripts folder itself is also owned and writable only by the root user. If a script that resides within the default Scripts folder does not meet these requirements, CCC will refuse to execute that script and the associated task will report an error.

After copying scripts into CCC's Scripts folder or making changes to those scripts, you can choose "Secure CCC's Scripts folder" from CCC's Utilities menu to correct any ownership or permissions concerns. Please note that these additional security requirements are only applied to scripts stored within the /Library/Application Support/com.bombich.ccc/Scripts folder. If you prefer to manage the security of your shell scripts on your own, you may store them in another location.

Example pre and post clone shell scripts

To use any of these example scripts, download the script and place it somewhere on your startup disk. By default, CCC looks in /Library/Application Support/com.bombich.ccc/Scripts.

parallels_pause.sh
This is a pre clone script that you can use to pause all currently-running Parallels VM containers. This script will also retain state information that can be read by the corresponding parallels_start.sh post clone script to resume these VMs after the backup task has completed. Note: This script relies on command-line tools offered only in Parallels Desktop for Mac Pro or Business Edition.

parallels_start.sh
This post clone script will resume any Parallels VM containers that were suspended by the parallels_pause.sh pre clone script. Note: This script relies on command-line tools offered only in Parallels Desktop for Mac Pro or Business Edition.

play_sound.sh
If you want to play a unique sound, use this script. You can plug in the path to any audio file of your liking or try one of the examples included.

eject_source_and_destination.sh
CCC's option to automatically unmount the destination volume is a volume-level task, not a device task. It's also limited to the destination. If you want to eject the destination device, or if you want to unmount or eject the source, use this post clone script instead. Note that ejecting a device will unmount all volumes on the device. Also note that this example script adds a 60-second delay to accommodate macOS's desire to automatically regenerate various cache files. This delay can be adjusted if necessary by editing the script.

pm_on_success.sh
This post clone script will perform the requested power management option (e.g. shutdown, restart, sleep) at the end of the backup task if the backup task completes without errors. Use this in lieu of one of the Power Management postflight options if you prefer the power management action does not occur when a task ends with errors (e.g. if the destination volume is missing).

quit_application.sh and open_application.sh
This pair of scripts can be used to quit and open an application before and after the backup task. Open these scripts in a text editor to define the application that should be quit or opened.

post_to_slack.sh
This postflight script will post the status of your backup task to a Slack channel.

ifttt_maker.sh
This postflight script will post an IFTTT Maker Event of the status of your backup task.