\section*{Python Scripting}
\label{_ChapterStart60}
\index[general]{Python Scripting}
-\index[general]{Scripting!Pyton}
+\index[general]{Scripting!Python}
\addcontentsline{toc}{section}{Python Scripting}
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 scripting in Bacula is to
+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
\addcontentsline{toc}{subsection}{Python Configuration}
Python must be enabled during the configuration process by adding
-a \verb?--?enable-python, and possibly specifying an alternate
+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.
language, it is very efficient.
When the Director starts, it looks to see if you have a {\bf
-Scripts Directory} defined, if so, it looks in that director for
-a file named {\bf DirStartUp}. If it is found, Bacula will pass this
-file to Python for execution.
+Scripts Directory} Directive defined, 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.
-\subsection*{Bacula Evetns}
+\subsection*{Bacula Events}
\index[general]{Bacula Events}
\index[general]{Events}
\addcontentsline{toc}{subsection}{Bacula Events}
\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}, by importing the
+ 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
+ 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
\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
+ 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
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.
+ 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
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
+{\bf set\_events} method. There are three possible
events.
\begin{description}
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
\end{verbatim}
\normalsize
-Here, you JobEvents class method NewVolume will be called each time
+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 {\be set_events} variable. Note, this is a bit different
+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:
\end{verbatim}
\normalsize
-The following are the methods (subroutines) provided within the
-directory by the {\bf job} object.
+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} obbject in the Director has
+a number of methods (subroutines) that can be called. They
+are:
\begin{description}
-\item [set_events] The set_events takes a single
-argument, which is the instantation 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 [set\_events] The set\_events method takes a single
+ argument, which is the instantation 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.
+ 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.
+ 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
\begin{description}
\item [Priority] Read or set the Job priority.
-Note, that a Job Priority is effective only before
-the Job actually starts.
+ 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 [DirName] The name of the Director daemon.
-\item [Level]
-\item [Type]
-\item [JobId]
-\item [Client]
-\item [NumVols]
-\item [Pool]
-\item [Storage]
-\item [Catalog]
-\item [MediaType]
-\item [JobName]
-\item [JobStatus]
+
+\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.
+\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
NewVolume event.
\end{description}
+\subsection*{Python Console Command}
+\index[general]{Python Console Command}
+\index[general]{Console Command!Python}
+\addcontentsline{toc}{subsection}{Python Console Command}
+
+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.
+
+
+\subsection*{Python Example}
+\index[general]{Python Example}
+\index[general]{Example!Python}
+\addcontentsline{toc}{subsection}{Python Example}
An example script for the Director startup file is provided in
{\bf examples/python/DirStartup.py} as follows:
bacula.set_events(BaculaEvents()) # register daemon events desired
"""
- There are the Job events that you can receive.
+ These are the Job events that you can receive.
"""
class JobEvents:
def __init__(self):
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
job.JobReport="Python before New Volume set for Job.\n"
job.VolumeName=volname
+ 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