Difference between revisions of "Script API"

From The Open Source Backup Wiki (Amanda, MySQL Backup, BackupPC)
Jump to navigationJump to search
(reorganize examples, change _ to -, general editing)
 
(15 intermediate revisions by 7 users not shown)
Line 1: Line 1:
==Introduction==
+
=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, once for each [[DLE]] or once for each client host.  Uses for pre- and post-scripts include:
+
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 <tt>/usr/lib/amanda/application/</tt> (may be <tt>/usr/lib64/amanda/application/</tt> 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 stop and start database servers so that the binary backup is consistent.
* to take a snapshot of a database
+
* to take a snapshot of a database or a ZFS or LVM partition.
* to send emails or other notifications
+
* to send emails or other notifications.
 +
 
 +
There are sample applications in the <tt>application-src</tt> directory of the distribution.
  
 
= Script calling convention =
 
= Script calling convention =
This is subject to change
+
This is subject to change.
   /path/to/script [execute-on]+ [--config <config>] [--host <host>] [--disk <disk>] [--device <device>]
+
   /path/to/script [execute-on]+ [--config <config>] [--host <host>] [--disk <disk>] [--device <device>] [--level]* [--PROPERTY_NAME PROPERTY_VALUE]*
+
 
  input of fd0:
+
"execute-on" is a comma-separated list of one or more words of the form <tt>(pre|post)-(dle|host)-(amcheck|estimate|backup)</tt>.
    tool property (format TBD)
+
 
  output on fd1
+
The disk and device arguments to the script are provided only if the script is executed for a [[DLE]].
    free format, will go to the amanda debug file.
+
 
 +
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 <tt>amlog-script.pl</tt>.
 +
 
 +
Output from the script goes to fd1 in free format. It will go to the amanda debug file.
  
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:
+
'''Note:''' Some execute-on scripts only run on the server or on the client. The whole list is:
  pre-dle-selfcheck
 
  pre-host-selfcheck
 
  post-dle-selfcheck
 
  post-host-selfcheck
 
  pre-dle-estimate
 
  pre-host-estimate
 
  post-dle-estimate
 
  post-host-estimate
 
  pre-dle-backup
 
  pre-host-backup
 
  post-dle-backup
 
  post-host-backup
 
The disk and device arguments to the script are provided only if the script is executed for a DLE.
 
  
Pre- and post-scripts are part of the [[Application API]].
+
{| border="1" cellspacing="0" style="text-align: center;"
 +
|-
 +
! rowspan="2" | execute-on
 +
! colspan="2" | 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=
 
=How to use=
Scripts are defined in amanda.conf, and then referenced from a dumptype.
+
Define scripts in amanda.conf, and then reference them from a dumptype.
  
 
== Define the script in amanda.conf ==
 
== Define the script in amanda.conf ==
Define the "my_script" script using the "myscript" binary.
+
Define the "my_script" script using the "myscript" executable.
 
   define script-tool my-script {
 
   define script-tool my-script {
     "script-base"                       # inherit config of the script-base script-tool
+
     "script-base"                     # inherit config of the script-base script-tool
 
     comment "a comment"
 
     comment "a comment"
     plugin  "myscript"                # filename of the script, in the dumper dir
+
     plugin  "myscript"                # filename of the script located in /usr/lib/amanda/application/
     execute-where server              # or client
+
                                      # on either the client or the server depending on value of execute-where
     execute-on    pre-dle-backup
+
     execute-where server              # one of: server or client
     property "mailto" "amandabackup"  # can set arbitrary properties
+
     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 ==
 
== Use the script in a dumptype ==
 
Reference the script-tool with the <tt>script</tt> parameter:
 
Reference the script-tool with the <tt>script</tt> parameter:
Line 50: Line 152:
 
     script "my-script"
 
     script "my-script"
 
   }
 
   }
Note that the dumptype declaration ''must'' be below the script-tool declaration in the configuation file.
+
Note that the dumptype declaration ''must'' be below the script-tool declaration in the configuration file.
  
 
== Email example ==
 
== Email example ==
Line 83: Line 185:
 
     user-tar
 
     user-tar
 
     script {
 
     script {
       "sc-email"
+
       plugin "sc-email"
 
       execute-where client
 
       execute-where client
 
       execute-on    post-dle-backup, post-host-estimate
 
       execute-on    post-dle-backup, post-host-estimate
 
     }
 
     }
 
  } -1 local
 
  } -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 <tt>zfs-snapshot</tt> in the <tt>applications</tt> directory of the amanda distribution.

Latest revision as of 20:48, 1 September 2017

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.