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 the destination, 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 postflight tasks, click the Advanced Settings button at the bottom of CCC's main window.
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 preflight 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.
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 a task failure, though it will make a note of the event in the Errors tab of the Task History window.
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 Settings 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, rather these are "requests". 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.
These restart/shutdown requests are made on behalf of the logged-in user by the CCC Dashboard application, which runs in the currently-logged-in user's login session. The CCC Dashboard offers two separate approaches for making these requests. By default, the Dashboard will make the request immediately and directly to macOS. Alternatively, you can have the Dashboard make the request in the same manner as implemented by the options in the Apple () menu. Requests made via the Apple menu cause a prompt to appear indicating that the system will shutdown. At that time a 60-second timer will start to count down. The reboot/shutdown request will be made when the timer expires. This option is convenient if you think you might want to cancel the reboot/shutdown request. To change the setting, click the CCC icon in the menu bar to reveal the CCC Dashboard, select the Tasks tab in the Dashboard, then click the settings icon to reveal the setting.
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 postflight shell scripts may be the solution for you. Preflight 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 Settings 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.
Postflight 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 postflight 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 postflight scripts, underlying volume path for a disk image for preflight 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 postflight 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). 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/CCC Backup - Data".
Third parameter
- Preflight script: The underlying mountpoint for the volume that holds the destination disk image, if applicable.
- Postflight script: The exit status of the file copying phase of the backup task.
Fourth parameter
The path to the destination disk image, if applicable.
Controlling the CCC task via the preflight script exit status
If your preflight 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 preflight 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 Settings 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 postflight 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.
Making changes to the source with a preflight script
If the source is an APFS volume, CCC will create a snapshot on that volume prior to running your preflight script, and then pass the path to that mounted snapshot as the first parameter to your shell script. Please bear this in mind if you are implementing a preflight script that makes changes to the source. Those changes will not be reflected in the current backup. If you need those changes to be reflected in the current backup, specify the preflight script as a global preflight script in the Advanced section of CCC's Settings window.
Running a preflight script prior to evaluating the source and destination availability
Per-task preflight scripts run after CCC has evaluated the availability of the source and destination. This order is deliberate — CCC passes the path of the source and destination to the preflight script, and we guarantee that these paths are available and correct when your preflight script is called. If you need your preflight script to make changes to the source, or take special measures to make the source or destination available (e.g. establishing a VPN connection), then you can perform those tasks in CCC's Global Preflight Script, specified in CCC Settings > Advanced. If you would like to limit the functionality of your global preflight script to a specific task, you can add logic to your script for that purpose. This example global preflight script demonstrates how to do this.
AppleScripts are not supported
You cannot specify an AppleScript as a pre- or postflight 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 postflight 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.
Another implication of running scripts as the root user is that interaction between the script and applications running via the logged-in user are generally not possible. For example, special steps are required if you want to open or close an application. See the quit_application.sh and open_application.sh scripts at the bottom of this document for an example of how to do this. Interaction with those applications usually will not work.
Security implications of pre- and postflight 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 postflight 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 postflight 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 preflight 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 postflight 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 postflight script will resume any Parallels VM containers that were suspended by the parallels_pause.sh preflight 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 postflight 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 snapshot creation on the destination.
pm_on_success.sh
This postflight 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.