Script API

Introduction

Use pre- and post-scripts to execute scripts before or after certain amanda commands. In most cases, the scripts can be executed on the client or server. They must be on the client or server accordingly in /usr/lib/amanda/application/ (may be /usr/lib64/amanda/application/ if a 64-bit install). The scripts can be executed once for each DLE or once for each client host. Uses for pre- and post-scripts include:

• to stop and start database servers so that the binary backup is consistent.
• to take a snapshot of a database or a ZFS or LVM partition.
• to send emails or other notifications.

There are sample applications in the application-src directory of the distribution.

Script calling convention

This is subject to change.

 /path/to/script [execute-on]+ [--config <config>] [--host <host>] [--disk <disk>] [--device <device>] [--level]* [--PROPERTY_NAME PROPERTY_VALUE]*

"execute-on" is a comma-separated list of one or more words of the form (pre|post)-(dle|host)-(amcheck|estimate|backup).

The disk and device arguments to the script are provided only if the script is executed for a DLE.

This syntax is designed for Perl's GetOptions module ("use Getopt::Long;"). Script properties work just like application properties: they are insensitive to case, and - (dash) and _ (underscore) are interchangeable. For an example, look at the level argument in amlog-script.pl.

Output from the script goes to fd1 in free format. It will go to the amanda debug file.

Note: Some execute-on scripts only run on the server or on the client. The whole list is:

execute-on	execute where
	server	client
pre-dle-amcheck	X	X
pre-host-amcheck	X	X
post-dle-amcheck	X	X
post-host-amcheck	X	X
pre-dle-estimate	X	X
pre-host-estimate	X	X
post-dle-estimate	X	X
post-host-estimate	X	X
pre-dle-backup	X	X
pre-host-backup	X	-
post-dle-backup	X	X
post-host-backup	X	-
pre-recover	-	X
post-recover	-	X
pre-dle-recover	-	X
post-dle-recover	-	X
inter-dle-recover	-	X

How to use

Define scripts in amanda.conf, and then reference them from a dumptype.

Define the script in amanda.conf

Define the "my_script" script using the "myscript" executable.

 define script-tool my-script {
    "script-base"                     # inherit config of the script-base script-tool
    comment "a comment"
    plugin  "myscript"                # filename of the script located in /usr/lib/amanda/application/
                                      # on either the client or the server depending on value of execute-where
    execute-where server              # one of: server or client
    execute-on    pre-dle-backup      # when to execute.
    property "mailto" "amandabackup"  # set arbitrary properties
 }

Multiple values for the same property can be defined two different ways. For the property foo:

property "foo" "bar" "baz" "snark"

or

property "foo" "bar"
property append "foo" "baz"
property append "foo" "snark"

The script will see a command line with this snippet:

--foo bar --foo baz --foo snark

Again, this syntax is designed for Perl's GetOptions module.

The file name and script name can be different. So you could create several script-tool definitions using the same script, and the difference between them might be different parameters.

Send property to the application

A pre-dle-amcheck script running on the client can set a property for the application 'selfcheck' command.

A pre-dle-estimate script running on the client can set a property for the application 'estimate' command.

A pre-dle-backup script running on the client can set a property for the application 'backup' command.

The script must print a line to stdout with the 'PROPERTY' keyword followed by the property name and property value

eg. PROPERTY directory /new/path

And the application will get the '--directory=/new/path' argument.

Use the script in a dumptype

Reference the script-tool with the script parameter:

 define dumptype user-tar-scripted {
   user-tar
   script "my-script"
 }

Note that the dumptype declaration must be below the script-tool declaration in the configuration file.

Email example

 define script-tool sc-email {
   comment "email me before this DLE is backed up"
   plugin  "script-email"
   execute-on pre-dle-backup
   execute-where server
   property "mailto" "martinea"
 }

 define dumptype user-tar-email {
   user-tar
   script "sc-email"
 }

Complex Examples

Just as you can include dumptypes in a DLE, you can include script-tool definitions in a dumptype:

 define dumptype user-tar-email2 {
   user-tar
   script {
     "sc-email"
     execute-where client
     execute-on    post-dle-backup, post-host-estimate
   }
 }

You can even combine all of this in a DLE:

myhost /my/disk {
   user-tar
   script {
     plugin "sc-email"
     execute-where client
     execute-on    post-dle-backup, post-host-estimate
   }
} -1 local

Backup using ZFS snapshots on OpenSolaris

amanda.conf should have ZFS snapshots defined as "script-tool" definition". You should use amgtar for the actual backup.

define script-tool script_zfs_snapshot {
  comment "zfs-snapshot"
  plugin "zfs-snapshot"
  execute-where client
  execute-on pre-dle-amcheck, post-dle-amcheck, pre-dle-estimate, post-dle-estimate, pre-dle-backup, post-dle-backup
  property "DF-PATH"  "/usr/sbin/df"
  property "ZFS-PATH" "/usr/sbin/zfs"
}

define application-tool app_amgtar {
  comment "amgtar"
  plugin "amgtar"
  property "ATIME-PRESERVE" "no"
}

define dumptype zfs-snapshot {
  program "APPLICATION"
  application "app_amgtar"
  script "script_zfs_snapshot"
  auth "bsdtcp"
}

An example disklist entry would be

opensolaris.mycompany.com /zpool/testfs/data zfs-snapshot

There is a sample zfs-snapshot in the applications directory of the amanda distribution.