Difference between revisions of "Script API"

From The Open Source Backup Wiki (Amanda, MySQL Backup, BackupPC)
Jump to navigationJump to search
m (Making it more clear where the script should be placed)
(Added information about the combination of execute_on and execute_where)
Line 13: Line 13:
  
 
execute-on is a comma-separated list of one or more words of the form <tt>(pre|post)-(dle|host)-(selfcheck|estimate|backup)</tt>.  The whole list is:
 
execute-on is a comma-separated list of one or more words of the form <tt>(pre|post)-(dle|host)-(selfcheck|estimate|backup)</tt>.  The whole list is:
  pre-dle-selfcheck
+
 
  pre-host-selfcheck
+
{| border="1" cellspacing="0" style="text-align: center;"
  post-dle-selfcheck
+
|-
  post-host-selfcheck
+
! rowspan="2" | execute-on
  pre-dle-estimate
+
! colspan="2" | execute-where
  pre-host-estimate
+
|-
  post-dle-estimate
+
! server
  post-host-estimate
+
! client
  pre-dle-backup
+
|-
  pre-host-backup
+
| pre-dle-selfcheck
  post-dle-backup
+
| ?
  post-host-backup
+
| ?
  pre-recover
+
|-
  post-recover
+
| pre-host-selfcheck
  pre-dle-recover
+
| ?
  post-dle-recover
+
| ?
  inter-dle-recover
+
|-
 +
| post-dle-selfcheck
 +
| ?
 +
| ?
 +
|-
 +
| post-host-selfcheck
 +
| ?
 +
| ?
 +
|-
 +
| 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
 +
| ?
 +
| ?
 +
|-
 +
| post-recover
 +
| ?
 +
| ?
 +
|-
 +
| pre-dle-recover
 +
| ?
 +
| ?
 +
|-
 +
| post-dle-recover
 +
| ?
 +
| ?
 +
|-
 +
| inter-dle-recover
 +
| ?
 +
| ?
 +
|}
 +
 
 
The disk and device arguments to the script are provided only if the script is executed for a DLE.
 
The disk and device arguments to the script are provided only if the script is executed for a DLE.
  

Revision as of 19:15, 3 December 2009

Introduction

Pre- and post-scripts are use to execute scripts before or after certain amanda commands. The scripts can be executed on the client or server and must be located 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
  • to send emails or other notifications

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]*

 output on fd1
   free format, will go to the amanda debug file.

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

execute-on execute-where
server client
pre-dle-selfcheck ? ?
pre-host-selfcheck ? ?
post-dle-selfcheck ? ?
post-host-selfcheck ? ?
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 ? ?
post-recover ? ?
pre-dle-recover ? ?
post-dle-recover ? ?
inter-dle-recover ? ?

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

tool property format

Each property is passed as command line option, if a property have many values, then it have an option for each value.

How to use

Scripts are defined in amanda.conf, and then referenced from a dumptype.

Define the script in amanda.conf

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

 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              # or client
    execute-on    pre-dle-backup
    property "mailto" "amandabackup"  # can set arbitrary properties
 }

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 configuation 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 {
     "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