Common Reference

Writing a Custom Backup/Restore Script

The synopsis of the custom script is as follows:

SCRIPT {-backup|-restore} -properties [FILE] -options [OPTIONS]

Where:

-backup - indicates that the script should work in the backup mode and create a backup.
-restore - indicates that the script should work in the restore mode and restore a previous backup.
-properties - defines the name of the properties file. When called in backup mode, the properties file should be updated by the script with the location of the generated backup file. When called in restore mode, the file should be examined by the script to determine the backup file that will be used to perform the restore operation.
-options - specifies any unique options to the script.

The custom script must support the following:

The script must be capable of performing both the backup and the restore operation. Tungsten Replicator selects the operation by providing the -backup or -restore option to the script on the command-line.
The script must parse command-line arguments to extract the operation type, properties file and other settings.
Accept the name of the properties file to be used during the backup process. This is supplied on the command-line using the format:
```
-properties FILENAME
```
The properties file is used by Tungsten Replicator to exchange information about the backup or restore.
Must parse any additional options supplied on the command-line using the format:
```
-options ARG1=VAL1&amp;ARG2=VAL2
```
Must be responsible for executing whatever steps are required to create a consistent snapshot of the dataserver
Must place the contents of the database backup into a single file. If the backup process generates multiple files, then the contents should be packaged using tar or zip.
The script has to determine the files that were generated during the backup process and collect them into a single file as appropriate.
Must update the supplied properties with the name of the backup file generated, as follows:
```
file=BACKUPFILE
```
If the file has not been updated with the information, or the file cannot be found, then the backup is considered to have failed.
Once the backup process has completed, the backup file specified in the properties file will be moved to the configured backup location (for example /opt/continuent/backups).
Tungsten Replicator will forward all STDOUT and STDERR from the script to the log file script.log within the log directory. This file is recreated each time a backup is executed.
Script should have an exit (return) value of 0 for success, and 1 for failure. The script is responsible for handling any errors in the underlying backup tool or script used to perform the backup, but it must then pass the corresponding success or failure condition using the exit code.

A sample Ruby script that creates a simple text file as the backup content, but demonstrates the core operations for the script is shown below:

/usr/bin/env ruby
require "/opt/continuent/tungsten/cluster-home/lib/ruby/tungsten"
require "/opt/continuent/tungsten/tungsten-replicator/lib/ruby/backup"
class MyCustomBackupScript < TungstenBackupScript
def backup
  TU.info("Take a backup with arg1 = #{@options[:arg1]} and myarg = #
{@options[:myarg]}")
  storage_file = "/opt/continuent/backups/backup_" +
Time.now.strftime("%Y-%m-%d_%H-%M") + "_" + rand(100).to_s()
  # Take a backup of the server and store the information to
storage_file
  TU.cmd_result("echo 'my backup' > #{storage_file}")
  # Write the filename to the final storage file
  TU.cmd_result("echo \"file=#{storage_file}\" > #
{@options[:properties]}")
end
def restore
  storage_file = TU.cmd_result(". #{@options[:properties]}; echo
$file")
  TU.info("Restore a backup from #{storage_file} with arg1 = #
{@options[:arg1]} and myarg = #{@options[:myarg]}")
  # Process the contents of storage_file to restore into the database
server
end

An alternative script using Perl is provided below:

#!/usr/bin/perl 

use strict;
use warnings;
use Getopt::Long;
use IO::File;

my $argstring = join(' ',@ARGV);

my ($backup,$restore,$properties,$options) = (0,0,'','');

my $result = GetOptions("backup" => \$backup,
    "restore" => \$restore,
    "properties=s" => \$properties,
    "options=s" => \$options,
  );

if ($backup)
{
  my ($sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst) = localtime(time);
  my $backupfile = sprintf('mcbackup.%04d%02d%02d-%02d%02d%02d-%02d.dump',
         ($year+1900),$mon,$mday,$hour,$min,$sec,$$);
  
  my $out = IO::File->new($backupfile,'w') or die "Couldn't open the backup file: $backupfile";
  
# Fake backup data

  print $out "Backup data!
";

  $out->close();
  
# Update the properties file
  my $propfile = IO::File->new($properties,'w') or die "Couldn't write to the properties file";
  print $propfile "file=$backupfile
";
  $propfile->close();
}

if ($restore)
{
  warn "Would be restoring information using $argstring
";
}

exit 0;

Enabling a Custom Backup Script

To enable a custom backup script, the installation must be updated through tpm to use the script backup method. To update the configuration:

Create or copy the backup script into a suitable location, for example /opt/continuent/share.
Copy the script to each of the datasources within your dataservice.
Update the configuration using tpm. The backup-method should be set to script, and the directory location set using the backup-script option:
```
backup-method=script
backup-script=/opt/continuent/share/mcbackup.pl
backup-online=true
```
The backup-online option indicates whether the backup script operates in online or offline mode. If set to false, replicator must be in the offline state before the backup process is started.
To pass additional arguments or options to the script, use the replicator.backup.agent.script.options property to supply a list of ampersand separate key/value pairs, for example:
```
property=replicator.backup.agent.script.options="arg1=val1&amp;myarg=val2"
```
These are the custom parameters which are supplied to the script as the value of the options parameter when the script is called.

Once the backup script has been enabled within the configuration it can be used when performing a backup through the standard backup or restore interface:

For example, within cctrl for Tungsten Clustering use:

[LOGICAL:EXPERT] /alpha > datasource host2 backup script

or, for Standalone Tungsten Replicator usage:

shell> trepctl -host host2 backup -backup script

note

Note that the name of the backup method is script, not the actual name of the script being used.

Enabling a Custom Backup Script​

Enabling a Custom Backup Script