How to Create a Custom Transport Script for Backups in cPanel Print

Overview

The Backup Configuration feature allows users to create a custom destination for their backups.

Create a custom transport script

The custom transport script is a script that you must provide for each custom backup destination that you set up in WHM’s Backup Configuration interface (WHM » Home » Backups » Backup Configuration). You can enter the transport script’s absolute path via the Script setting for the Custom destination type in the Additional Destinations section.

Script operation

The following rules affect how the script interacts with the system:

• The script runs once per command.
• The script cannot save state information between commands.
• The system does not reuse the connection between commands. Instead, each time that the script runs, the system creates the connection to the remote custom destination, and then drops it after the script runs.

The system passes information to the script, through the command line, in the following order:

1. Command name.
2. Current directory.
3. Command specific parameters.
4. Host.
5. Username.

The system passes the password information to the script through the environment.

Script commands

The script must implement the following commands:

Backups run each of these commands individually while the system transports the backup file and validates the destination.

Your script should return any output to STDOUT to return data to the user.

Templates

You can use the /usr/local/cpanel/scripts/custom_backup_destination.pl.skeleton script in cPanel & WHM as a template to create your own custom_backup_destination.pl script. For a sample backup transport script, see the /usr/local/cpanel/scripts/custom_backup_destination.pl.sample script.

The system passes most variables as arguments to the command line. If your script does not pass one of the hardcoded arguments to the core functions, the system will display all valid arguments in the global %commandshash.

Code examples

Use statements

Begin the script with the standard use statements. Include any modules that you may need for your transport:

1
2
3
4
5
6
7

use strict;
use warnings;
use Cwd qw(getcwd abs_path);
use File::Spec;
use File::Copy;
use File::Path qw(make_path remove_tree);
use autodie qw(:all copy);

The %commands list

1
2
3
4
5
6
7
8
9

my %commands = (
    put    => \&my_put,
    get    => \&my_get,
    ls     => \&my_ls,
    mkdir  => \&my_mkdir,
    chdir  => \&my_chdir,
    rmdir  => \&my_rmdir,
    delete => \&my_delete,
);

The %command subroutines

Every call to the script begins with a command and a local directory. You must pass the command line arguments in the following order:

• $cmd — The command.
• $local_dir — The local directory.
• @args — The command’s arguments.
• $host — Optional. The remote destination’s hostname or IP address.
• $user — Optional. The remote destination’s account username.
• $password — Optional. The remote destination’s password.

Use the arguments that are specific to each of the commands and variables.

1
2
3

my ( $cmd, $local_dir, @args, $host, $user ) = @ARGV;
my $password = $ENV{'PASSWORD'};
 usage() unless exists $commands{$cmd};

The put functions

The put function directs the script to upload or copy a local file to a remote destination. This function works similarly to the FTP put command.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

sub my_put {
    my ( $local, $remote, $host, $user ) = @_;   # Required argument order

    my $password = $ENV{'PASSWORD'};     # Enclose the password in the ENV hash

    $remote = convert_path($remote);     # the remote file's variable

    my ( undef, $dir, undef ) = File::Spec->splitpath($remote); # Make sure the full destination directory exists
    make_path($dir) unless ( $dir and -d $dir );

    copy( $local, $remote ); # copy the local file to the remote file
    return;
}

The get function

The get function directs the script to download or retrieve a local file from a remote destination. This function works similarly to the FTP get command.

1
2
3
4
5
6
7
8

sub my_get {
    my ( $remote, $local, $host, $user ) = @_;
    my $password = $ENV{'PASSWORD'};
    $remote = convert_path($remote);

    copy( $remote, $local );
    return;
}

The ls function

The ls function pulls the listing of a remote file or directory, similar to FTP or a local ls argument on the command line.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

sub my_ls {
    my ( $path, $host, $user ) = @_;

    my $password = $ENV{'PASSWORD'};

    $path = convert_path($path);

    my $ls = `ls -al $path`;

    # Remove the annoying 'total' line
    $ls =~ s|^total[^\n]*\n||;

    print $ls;
    return;
}

The mkdir function

The mkdir function ensures that a directory exists on the remote machine and that the system uploads the backup to a real path.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

sub my_mkdir {
    my ( $path, $recurse, $host, $user ) = @_;

    my $password = $ENV{'PASSWORD'};

    $path = convert_path($path);

    make_path($path);

    die "Failed to create $path" unless -d $path;
    return;
}

The chdir function

The chdir function allows you to store the working directory and keep the session information between operations.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

sub my_chdir {
    my ( $path, $host, $user ) = @_;
    my $password = $ENV{'PASSWORD'};

    $path = convert_path($path);
    chdir $path;

    print get_sub_directory( getcwd() ) . "\n";
    return;
}

The rmdir function

The rmdir function removes a directory and recursively deletes everything below the given directory. Based on which transport you use, you may need to remove all the files and directories below the given directory before the system can execute this function.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

sub my_rmdir {
    my ( $path, $host, $user ) = @_;

    my $password = $ENV{'PASSWORD'};

    $path = convert_path($path);

    remove_tree($path);

    die "$path still exists" if -d $path;
    return;
}

The delete function

The delete function deletes a single file.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

sub my_delete {
    my ( $path, $host, $user ) = @_;

    my $password = $ENV{'PASSWORD'};

    $path = convert_path($path);

    unlink $path;
    return;
}

Basic error check

1
2

sub my_delete {
usage() if ( @ARGV < 2 );

1
2
3
4
5
6
7

sub usage {
    my @cmds = sort keys %commands;
    print STDERR "This script is for implementing a custom backup destination\n";
    print STDERR "It requires the following arguments:  cmd, local_dir, cmd_args\n";
    print STDERR "These are the valid commands:  @cmds\n";
    exit 1;
}

The $cmd command

Use the %command hash to call each command’s specific code block.

$commands{$cmd}->(@args);