\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
\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 directory 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.
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
-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.
+ 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 [DoesVolumeExist] The DoesVolumeExist 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. (not functional yet)
\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 [Level] This attribute contains a string representing the Job
+ level, e.g. Full, Differential, Incremental, ...
+\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:
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