Difference between revisions of "Script API"

From The Open Source Backup Wiki (Amanda, MySQL Backup, BackupPC)
Jump to navigationJump to search
 
 
(16 intermediate revisions by 7 users not shown)
Line 1: Line 1:
==Introduction==
+
=Introduction=
Pre&Post script are use to execute script before or after amanda command, they can be executed on the client or server, once for each DLE or once for each client.
+
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 take a snapshot of a database or a ZFS or LVM partition.
 +
* 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]*
 +
 
 +
"execute-on" is a comma-separated list of one or more words of the form <tt>(pre|post)-(dle|host)-(amcheck|estimate|backup)</tt>.
 +
 
 +
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 <tt>amlog-script.pl</tt>.
 +
 
 +
Output from the script goes to fd1 in free format. It will go to the amanda debug file.
  
  input of fd0:
+
'''Note:''' Some execute-on scripts only run on the server or on the client. The whole list is:
    tool property
 
  output on fd1
 
    free format, will go to the amanda debug file.
 
  
execute_on can be one or many of:
+
{| border="1" cellspacing="0" style="text-align: center;"
  pre-dle-selfcheck
+
|-
  pre-host-selfcheck
+
! rowspan="2" | execute-on
  post-dle-selfcheck
+
! colspan="2" | execute where
  post-host-selfcheck
+
|-
  pre-dle-estimate
+
! server
  pre-host-estimate
+
! client
  post-dle-estimate
+
|-
  post-host-estimate
+
| pre-dle-amcheck
  pre-dle-backup
+
| X
  pre-host-backup
+
| X
  post-dle-backup
+
|-
  post-host-backup
+
| pre-host-amcheck
Disk and device are provided only if the script is executed for a DLE.
+
| 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=
== The script must be defined in amanda.conf ==
+
Define scripts in amanda.conf, and then reference them from a dumptype.
Define the "my_script" script using the "myscript" binary.
+
 
   define script-tool my_script {
+
== 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"
 
     comment "a comment"
    "my_script"                      # inherit config of the my_app application
+
     plugin  "myscript"                # filename of the script located in /usr/lib/amanda/application/
     plugin  "myscript"                # name of the application, it must be installed in dumper dir
+
                                      # on either the client or the server depending on value of execute-where
     execute_where server              # or client
+
     execute-where server              # one of: server or client
     execute_on   pre-dle-backup
+
     execute-on   pre-dle-backup     # when to execute.
     property "mailto" "amandabackup"  # can set property
+
     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 <tt>script</tt> parameter:
 +
  define dumptype user-tar-scripted {
 +
    user-tar
 +
    script "my-script"
 
   }
 
   }
The dumptype must specify the script to use
+
Note that the dumptype declaration ''must'' be below the script-tool declaration in the configuration file.
  
== script-email example ==
+
== Email example ==
 
   define script-tool sc-email {
 
   define script-tool sc-email {
     comment "script-email"
+
     comment "email me before this DLE is backed up"
 
     plugin  "script-email"
 
     plugin  "script-email"
     execute_on pre-dle-backup
+
     execute-on pre-dle-backup
     execute_where server                 # or client
+
     execute-where server
 
     property "mailto" "martinea"
 
     property "mailto" "martinea"
 
   }
 
   }
your dumptype must include: script "sc-email"
+
 
   define dumptype user-tar-email {
 
   define dumptype user-tar-email {
 
     user-tar
 
     user-tar
 
     script "sc-email"
 
     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 {
 
   define dumptype user-tar-email2 {
Line 57: Line 175:
 
     script {
 
     script {
 
       "sc-email"
 
       "sc-email"
       execute_where client
+
       execute-where client
       execute_on   post-dle-backup, post-host-estimate
+
       execute-on   post-dle-backup, post-host-estimate
 
     }
 
     }
 
   }
 
   }
Your DLE entry must use the user-tar-email or user-tar-email2 dumptype
+
 
 +
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 <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.