+++ /dev/null
-%%
-%%
-
-\chapter{Python Scripting}
-\label{PythonChapter}
-\index[general]{Python Scripting}
-\index[general]{Scripting!Python}
-
-You may be asking what Python is and why a scripting language is
-needed in Bacula. The answer to the first question is that Python
-is an Object Oriented scripting language with features similar
-to those found in Perl, but the syntax of the language is much
-cleaner and simpler. The answer to why have scripting in Bacula is to
-give the user more control over the whole backup process. Probably
-the simplest example is when Bacula needs a new Volume name, with
-a scripting language such as Python, you can generate any name
-you want, based on the current state of Bacula.
-
-\section{Python Configuration}
-\index[general]{Python Configuration}
-\index[general]{Configuration!Python}
-
-Python must be enabled during the configuration process by adding
-a \verb:--:with-python, and possibly specifying an alternate
-directory if your Python is not installed in a standard system
-location. If you are using RPMs you will need the python-devel package
-installed.
-
-When Python is configured, it becomes an integral part of Bacula and
-runs in Bacula's address space, so even though it is an interpreted
-language, it is very efficient.
-
-When the Director starts, it looks to see if you have a {\bf
-Scripts Directory} Directive defined (normal default {\bf
-/etc/bacula/scripts}, if so, it looks in that directory for a file named
-{\bf DirStartUp.py}. If it is found, Bacula will pass this file to Python
-for execution. The {\bf Scripts Directory} is a new directive that you add
-to the Director resource of your bacula-dir.conf file.
-
-Note: Bacula does not install Python scripts by default because these
-scripts are for you to program. This means that with a default
-installation with Python enabled, Bacula will print the following error
-message:
-
-\begin{verbatim}
-09-Jun 15:14 bacula-dir: ERROR in pythonlib.c:131 Could not import
-Python script /etc/bacula/scripts/DirStartUp. Python disabled.
-\end{verbatim}
-
-The source code directory {\bf examples/python} contains sample scripts
-for DirStartUp.py, SDStartUp.py, and FDStartUp.py that you might want
-to use as a starting point. Normally, your scripts directory (at least
-where you store the Python scripts) should be writable by Bacula, because
-Python will attempt to write a compiled version of the scripts (e.g.
-DirStartUp.pyc) back to that directory.
-
-When starting with the sample scripts, you can delete any part that
-you will not need, but you should keep all the Bacula Event and Job Event
-definitions. If you do not want a particular event, simply replace the
-existing code with a {\bf noop = 1}.
-
-\section{Bacula Events}
-\index[general]{Bacula Events}
-\index[general]{Events}
-A Bacula event is a point in the Bacula code where Bacula
-will call a subroutine (actually a method) that you have
-defined in the Python StartUp script. Events correspond
-to some significant event such as a Job Start, a Job End,
-Bacula needs a new Volume Name, ... When your script is
-called, it will have access to all the Bacula variables
-specific to the Job (attributes of the Job Object), and
-it can even call some of the Job methods (subroutines)
-or set new values in the Job attributes, such as the
-Priority. You will see below how the events are used.
-
-\section{Python Objects}
-\index[general]{Python Objects}
-\index[general]{Objects!Python}
-
-There are four Python objects that you will need to work with:
-\begin{description}
-\item [The Bacula Object]
- The Bacula object is created by the Bacula daemon (the Director
- in the present case) when the daemon starts. It is available to
- the Python startup script, {\bf DirStartup.py}, by importing the
- Bacula definitions with {\bf import bacula}. The methods
- available with this object are described below.
-
-\item [The Bacula Events Class]
- You create this class in the startup script, and you pass
- it to the Bacula Object's {\bf set\_events} method. The
- purpose of the Bacula Events Class is to define what global
- or daemon events you want to monitor. When one of those events
- occurs, your Bacula Events Class will be called at the method
- corresponding to the event. There are currently three events,
- JobStart, JobEnd, and Exit, which are described in detail below.
-
-\item [The Job Object]
- When a Job starts, and assuming you have defined a JobStart method
- in your Bacula Events Class, Bacula will create a Job Object. This
- object will be passed to the JobStart event. The Job Object has a
- has good number of read-only members or attributes providing many
- details of the Job, and it also has a number of writable attributes
- that allow you to pass information into the Job. These attributes
- are described below.
-
-\item [The Job Events Class]
- You create this class in the JobStart method of your Bacula Events
- class, and it allows you to define which of the possible Job Object
- events you want to see. You must pass an instance of your Job Events
- class to the Job Object set\_events() method.
- Normally, you will probably only have one
- Job Events Class, which will be instantiated for each Job. However,
- if you wish to see different events in different Jobs, you may have
- as many Job Events classes as you wish.
-\end{description}
-
-
-The first thing the startup script must do is to define what global Bacula
-events (daemon events), it wants to see. This is done by creating a
-Bacula Events class, instantiating it, then passing it to the
-{\bf set\_events} method. There are three possible
-events.
-
-\begin{description}
-\item [JobStart]
- \index[general]{JobStart}
- This Python method, if defined, will be called each time a Job is started.
- The method is passed the class instantiation object as the first argument,
- and the Bacula Job object as the second argument. The Bacula Job object
- has several built-in methods, and you can define which ones you
- want called. If you do not define this method, you will not be able
- to interact with Bacula jobs.
-
-\item [JobEnd]
- This Python method, if defined, will be called each time a Job terminates.
- The method is passed the class instantiation object as the first argument,
- and the Bacula Job object as the second argument.
-
-\item [Exit]
- This Python method, if defined, will be called when the Director terminates.
- The method is passed the class instantiation object as the first argument.
-\end{description}
-
-Access to the Bacula variables and methods is done with:
-
- import bacula
-
-The following are the read-only attributes provided by the bacula object.
-\begin{description}
-\item [Name]
-\item [ConfigFile]
-\item [WorkingDir]
-\item [Version] string consisting of "Version Build-date"
-\end{description}
-
-
-A simple definition of the Bacula Events Class might be the following:
-
-\footnotesize
-\begin{verbatim}
-import sys, bacula
-class BaculaEvents:
- def JobStart(self, job):
- ...
-\end{verbatim}
-\normalsize
-
-Then to instantiate the class and pass it to Bacula, you
-would do:
-
-\footnotesize
-\begin{verbatim}
-bacula.set_events(BaculaEvents()) # register Bacula Events wanted
-\end{verbatim}
-\normalsize
-
-And at that point, each time a Job is started, your BaculaEvents JobStart
-method will be called.
-
-Now to actually do anything with a Job, you must define which Job events
-you want to see, and this is done by defining a JobEvents class containing
-the methods you want called. Each method name corresponds to one of the
-Job Events that Bacula will generate.
-
-A simple Job Events class might look like the following:
-
-\footnotesize
-\begin{verbatim}
-class JobEvents:
- def NewVolume(self, job):
- ...
-\end{verbatim}
-\normalsize
-
-Here, your JobEvents class method NewVolume will be called each time
-the Job needs a new Volume name. To actually register the events defined
-in your class with the Job, you must instantiate the JobEvents class and
-set it in the Job {\bf set\_events} variable. Note, this is a bit different
-from how you registered the Bacula events. The registration process must
-be done in the Bacula JobStart event (your method). So, you would modify
-Bacula Events (not the Job events) as follows:
-
-\footnotesize
-\begin{verbatim}
-import sys, bacula
-class BaculaEvents:
- def JobStart(self, job):
- events = JobEvents() # create instance of Job class
- job.set_events(events) # register Job events desired
- ...
-\end{verbatim}
-\normalsize
-
-When a job event is triggered, the appropriate event definition is
-called in the JobEvents class. This is the means by which your Python
-script or code gets control. Once it has control, it may read job
-attributes, or set them. See below for a list of read-only attributes,
-and those that are writable.
-
-In addition, the Bacula {\bf job} object in the Director has
-a number of methods (subroutines) that can be called. They
-are:
-\begin{description}
-\item [set\_events] The set\_events method takes a single
- argument, which is the instantiation of the Job Events class
- that contains the methods that you want called. The method
- names that will be called must correspond to the Bacula
- defined events. You may define additional methods but Bacula
- will not use them.
-\item [run] The run method takes a single string
- argument, which is the run command (same as in the Console)
- that you want to submit to start a new Job. The value
- returned by the run method is the JobId of the job that
- started, or -1 if there was an error.
-\item [write] The write method is used to be able to send
- print output to the Job Report. This will be described later.
-\item[cancel] The cancel method takes a single integer argument,
- which is a JobId. If JobId is found, it will be canceled.
-\item [DoesVolumeExist] The DoesVolumeExist method takes a single
- string argument, which is the Volume name, and returns
- 1 if the volume exists in the Catalog and 0 if the volume
- does not exist.
-\end{description}
-
-The following attributes are read/write within the Director
-for the {\bf job} object.
-
-\begin{description}
-\item [Priority] Read or set the Job priority.
- Note, that setting a Job Priority is effective only before
- the Job actually starts.
-\item [Level] This attribute contains a string representing the Job
- level, e.g. Full, Differential, Incremental, ... if read.
- The level can also be set.
-\end{description}
-
-The following read-only attributes are available within the Director
-for the {\bf job} object.
-
-\begin{description}
-\item [Type] This attribute contains a string representing the Job
- type, e.g. Backup, Restore, Verify, ...
-\item [JobId] This attribute contains an integer representing the
- JobId.
-\item [Client] This attribute contains a string with the name of the
- Client for this job.
-\item [NumVols] This attribute contains an integer with the number of
- Volumes in the Pool being used by the Job.
-\item [Pool] This attribute contains a string with the name of the Pool
- being used by the Job.
-\item [Storage] This attribute contains a string with the name of the
- Storage resource being used by the Job.
-\item [Catalog] This attribute contains a string with the name of the
- Catalog resource being used by the Job.
-\item [MediaType] This attribute contains a string with the name of the
- Media Type associated with the Storage resource being used by the Job.
-\item [Job] This attribute contains a string containing the name of the
- Job resource used by this job (not unique).
-\item [JobName] This attribute contains a string representing the full
- unique Job name.
-\item [JobStatus] This attribute contains a single character string
- representing the current Job status. The status may change
- during execution of the job. It may take on the following
- values:
- \begin{description}
- \item [C] Created, not yet running
- \item [R] Running
- \item [B] Blocked
- \item [T] Completed successfully
- \item [E] Terminated with errors
- \item [e] Non-fatal error
- \item [f] Fatal error
- \item [D] Verify found differences
- \item [A] Canceled by user
- \item [F] Waiting for Client
- \item [S] Waiting for Storage daemon
- \item [m] Waiting for new media
- \item [M] Waiting for media mount
- \item [s] Waiting for storage resource
- \item [j] Waiting for job resource
- \item [c] Waiting for client resource
- \item [d] Waiting on maximum jobs
- \item [t] Waiting on start time
- \item [p] Waiting on higher priority jobs
- \end{description}
-
-\item [Priority] This attribute contains an integer with the priority
- assigned to the job.
-\item [CatalogRes] tuple consisting of (DBName, Address, User,
- Password, Socket, Port, Database Vendor) taken from the Catalog resource
- for the Job with the exception of Database Vendor, which is
- one of the following: MySQL, PostgreSQL, SQLite, Internal,
- depending on what database you configured.
-\item [VolumeName]
- After a Volume has been purged, this attribute will contain the
- name of that Volume. At other times, this value may have no meaning.
-\end{description}
-
-The following write-only attributes are available within the
-Director:
-
-\begin{description}
-\item [JobReport] Send line to the Job Report.
-\item [VolumeName] Set a new Volume name. Valid only during the
- NewVolume event.
-\end{description}
-
-\section{Python Console Command}
-\index[general]{Python Console Command}
-\index[general]{Console Command!Python}
-
-There is a new Console command named {\bf python}. It takes
-a single argument {\bf restart}. Example:
-\begin{verbatim}
- python restart
-\end{verbatim}
-
-This command restarts the Python interpreter in the Director.
-This can be useful when you are modifying the DirStartUp script,
-because normally Python will cache it, and thus the
-script will be read one time.
-
-\section{Debugging Python Scripts}
-\index[general]{Debugging Python Scripts}
-In general, you debug your Python scripts by using print statements.
-You can also develop your script or important parts of it as a
-separate file using the Python interpreter to run it. Once you
-have it working correctly, you can then call the script from
-within the Bacula Python script (DirStartUp.py).
-
-If you are having problems loading DirStartUp.py, you will probably
-not get any error messages because Bacula can only print Python
-error messages after the Python interpreter is started. However, you
-may be able to see the error messages by starting Bacula in
-a shell window with the {\bf -d1} option on the command line. That
-should cause the Python error messages to be printed in the shell
-window.
-
-If you are getting error messages such as the following when
-loading DirStartUp.py:
-
-\begin{verbatim}
- Traceback (most recent call last):
- File "/etc/bacula/scripts/DirStartUp.py", line 6, in ?
- import time, sys, bacula
- ImportError: /usr/lib/python2.3/lib-dynload/timemodule.so: undefined
- symbol: PyInt_FromLong
- bacula-dir: pythonlib.c:134 Python Import error.
-\end{verbatim}
-
-It is because the DirStartUp script is calling a dynamically loaded
-module (timemodule.so in the above case) that then tries to use
-Python functions exported from the Python interpreter (in this case
-PyInt\_FromLong). The way Bacula is currently linked with Python does
-not permit this. The solution to the problem is to put such functions
-(in this case the import of time into a separate Python script, which
-will do your calculations and return the values you want. Then call
-(not import) this script from the Bacula DirStartUp.py script, and
-it all should work as you expect.
-
-
-
-
-
-\section{Python Example}
-\index[general]{Python Example}
-\index[general]{Example!Python}
-
-An example script for the Director startup file is provided in
-{\bf examples/python/DirStartup.py} as follows:
-
-\footnotesize
-\begin{verbatim}
-#
-# Bacula Python interface script for the Director
-#
-
-# You must import both sys and bacula
-import sys, bacula
-
-# This is the list of Bacula daemon events that you
-# can receive.
-class BaculaEvents(object):
- def __init__(self):
- # Called here when a new Bacula Events class is
- # is created. Normally not used
- noop = 1
-
- def JobStart(self, job):
- """
- Called here when a new job is started. If you want
- to do anything with the Job, you must register
- events you want to receive.
- """
- events = JobEvents() # create instance of Job class
- events.job = job # save Bacula's job pointer
- job.set_events(events) # register events desired
- sys.stderr = events # send error output to Bacula
- sys.stdout = events # send stdout to Bacula
- jobid = job.JobId; client = job.Client
- numvols = job.NumVols
- job.JobReport="Python Dir JobStart: JobId=%d Client=%s NumVols=%d\n" % (jobid,client,numvols)
-
- # Bacula Job is going to terminate
- def JobEnd(self, job):
- jobid = job.JobId
- client = job.Client
- job.JobReport="Python Dir JobEnd output: JobId=%d Client=%s.\n" % (jobid, client)
-
- # Called here when the Bacula daemon is going to exit
- def Exit(self, job):
- print "Daemon exiting."
-
-bacula.set_events(BaculaEvents()) # register daemon events desired
-
-"""
- These are the Job events that you can receive.
-"""
-class JobEvents(object):
- def __init__(self):
- # Called here when you instantiate the Job. Not
- # normally used
- noop = 1
-
- def JobInit(self, job):
- # Called when the job is first scheduled
- noop = 1
-
- def JobRun(self, job):
- # Called just before running the job after initializing
- # This is the point to change most Job parameters.
- # It is equivalent to the JobRunBefore point.
- noop = 1
-
- def NewVolume(self, job):
- # Called when Bacula wants a new Volume name. The Volume
- # name returned, if any, must be stored in job.VolumeName
- jobid = job.JobId
- client = job.Client
- numvol = job.NumVols;
- print job.CatalogRes
- job.JobReport = "JobId=%d Client=%s NumVols=%d" % (jobid, client, numvol)
- job.JobReport="Python before New Volume set for Job.\n"
- Vol = "TestA-%d" % numvol
- job.JobReport = "Exists=%d TestA-%d" % (job.DoesVolumeExist(Vol), numvol)
- job.VolumeName="TestA-%d" % numvol
- job.JobReport="Python after New Volume set for Job.\n"
- return 1
-
- def VolumePurged(self, job):
- # Called when a Volume is purged. The Volume name can be referenced
- # with job.VolumeName
- noop = 1
-
-
-
-\end{verbatim}
-\normalsize
projects / bacula / docs / blobdiff