4 \section*{Python Scripting}
5 \label{_ChapterStart60}
6 \index[general]{Python Scripting}
7 \index[general]{Scripting!Pyton}
8 \addcontentsline{toc}{section}{Python Scripting}
10 You may be asking what Python is and why a scripting language is
11 needed in Bacula. The answer to the first question is that Python
12 is an Object Oriented scripting language with features similar
13 to those found in Perl, but the syntax of the language is much
14 cleaner and simpler. The answer to why have scripting in Bacula is to
15 give the user more control over the whole backup process. Probably
16 the simplest example is when Bacula needs a new Volume name, with
17 a scripting language such as Python, you can generate any name
18 you want, based on the current state of Bacula.
20 \subsection*{Python Configuration}
21 \index[general]{Python Configuration}
22 \index[general]{Configuration!Python}
23 \addcontentsline{toc}{subsection}{Python Configuration}
25 Python must be enabled during the configuration process by adding
26 a \verb?--?enable-python, and possibly specifying an alternate
27 directory if your Python is not installed in a standard system
28 location. If you are using RPMs you will need the python-devel package
31 When Python is configured, it becomes an integral part of Bacula and
32 runs in Bacula's address space, so even though it is an interpreted
33 language, it is very efficient.
35 When the Director starts, it looks to see if you have a {\bf
36 Scripts Directory} defined, if so, it looks in that directory for
37 a file named {\bf DirStartUp}. If it is found, Bacula will pass this
38 file to Python for execution.
40 \subsection*{Bacula Evetns}
41 \index[general]{Bacula Events}
42 \index[general]{Events}
43 \addcontentsline{toc}{subsection}{Bacula Events}
44 A Bacula event is a point in the Bacula code where Bacula
45 will call a subroutine (actually a method) that you have
46 defined in the Python StartUp script. Events correspond
47 to some significant event such as a Job Start, a Job End,
48 Bacula needs a new Volume Name, ... When your script is
49 called, it will have access to all the Bacula variables
50 specific to the Job (attributes of the Job Object), and
51 it can even call some of the Job methods (subroutines)
52 or set new values in the Job attributes, such as the
53 Priority. You will see below how the events are used.
55 \subsection*{Python Objects}
56 \index[general]{Python Objects}
57 \index[general]{Objects!Python}
58 \addcontentsline{toc}{subsection}{Python Objects}
60 There are four Python objects that you will need to work with:
62 \item [The Bacula Object]
63 The Bacula object is created by the Bacula daemon (the Director
64 in the present case) when the daemon starts. It is available to
65 the Python startup script, {\bf DirStartup}, by importing the
66 Bacula definitions with {\bf import bacula}. The methods
67 available with this object are described below.
69 \item [The Bacula Events Class]
70 You create this class in the startup script, and you pass
71 it to the Bacula Object's {\bf set\_events} method. The
72 purpose of the Bacula Events Class is to define what global
73 or daemon events you want to monitor. When one of those events
74 occurs, your Bacula Events Class will be called at the method
75 corresponding to the event. There are currently three events,
76 JobStart, JobEnd, and Exit, which are described in detail below.
78 \item [The Job Object]
79 When a Job starts, and assuming you have defined a JobStart method
80 in your Bacula Events Class, Bacula will create a Job Object. This
81 object will be passed to the JobStart event. The Job Object has a
82 has good number of read-only members or attributes providing many
83 details of the Job, and it also has a number of writable attributes
84 that allow you to pass information into the Job. These attributes
87 \item [The Job Events Class]
88 You create this class in the JobStart method of your Bacula Events
89 class, and it allows you to define which of the possible Job Object
90 events you want to see. You must pass an instance of your Job Events
91 class to the Job Object set\_events() method.
92 Normally, you will probably only have one
93 Job Events Class, which will be instantiated for each Job. However,
94 if you wish to see different events in different Jobs, you may have
95 as many Job Events classes as you wish.
99 The first thing the startup script must do is to define what global Bacula
100 events (daemon events), it wants to see. This is done by creating a
101 Bacula Events class, instantiating it, then passing it to the
102 {\bf set\_events} method. There are three possible
107 \index[dir]{JobStart}
108 This Python method, if defined, will be called each time a Job is started.
109 The method is passed the class instantiation object as the first argument,
110 and the Bacula Job object as the second argument. The Bacula Job object
111 has several built-in methods, and you can define which ones you
112 want called. If you do not define this method, you will not be able
113 to interact with Bacula jobs.
116 This Python method, if defined, will be called each time a Job terminates.
117 The method is passed the class instantiation object as the first argument,
118 and the Bacula Job object as the second argument.
121 This Python method, if defined, will be called when the Director terminates.
122 The method is passed the class instantiation object as the first argument.
125 Access to the Bacula variables and methods is done with:
129 A simple definition of the Bacula Events Class might be the following:
135 def JobStart(self, job):
140 Then to instantiate the class and pass it to Bacula, you
145 bacula.set_events(BaculaEvents()) # register Bacula Events wanted
149 And at that point, each time a Job is started, your BaculaEvents JobStart
150 method will be called.
152 Now to actually do anything with a Job, you must define which Job events
153 you want to see, and this is done by defining a JobEvents class containing
154 the methods you want called. Each method name corresponds to one of the
155 Job Events that Bacula will generate.
157 A simple Job Events class might look like the following:
162 def NewVolume(self, job):
167 Here, your JobEvents class method NewVolume will be called each time
168 the Job needs a new Volume name. To actually register the events defined
169 in your class with the Job, you must instantiate the JobEvents class and
170 set it in the Job {\bf set\_events} variable. Note, this is a bit different
171 from how you registered the Bacula events. The registration process must
172 be done in the Bacula JobStart event (your method). So, you would modify
173 Bacula Events (not the Job events) as follows:
179 def JobStart(self, job):
180 events = JobEvents() # create instance of Job class
181 job.set_events(events) # register Job events desired
186 The following are the methods (subroutines) provided within the
187 directory by the {\bf job} object.
189 \item [set\_events] The set\_events takes a single
190 argument, which is the instantation of the Job Events class
191 that contains the methods that you want called. The method
192 names that will be called must correspond to the Bacula
193 defined events. You may define additional methods but Bacula
195 \item [run] The run method takes a single string
196 argument, which is the run command (same as in the Console)
197 that you want to submit to start a new Job. The value
198 returned by the run method is the JobId of the job that
199 started, or -1 if there was an error.
200 \item [write] The write method is used to be able to send
201 print output to the Job Report. This will be described later.
204 The following attributes are read/write within the Director
205 for the {\bf job} object.
208 \item [Priority] Read or set the Job priority.
209 Note, that a Job Priority is effective only before
210 the Job actually starts.
213 The following read-only attributes are available within the Director
214 for the {\bf job} object.
217 \item [DirName] The name of the Director daemon.
231 The following write-only attributes are available within the
235 \item [JobReport] Send line to the Job Report.
236 \item [VolumeName] Set a new Volume name. Valid only during the
241 An example script for the Director startup file is provided in
242 {\bf examples/python/DirStartup.py} as follows:
247 # Bacula Python interface script for the Director
250 # You must import both sys and bacula
253 # This is the list of Bacula daemon events that you
257 # Called here when a new Bacula Events class is
258 # is created. Normally not used
261 def JobStart(self, job):
263 Called here when a new job is started. If you want
264 to do anything with the Job, you must register
265 events you want to receive.
267 events = JobEvents() # create instance of Job class
268 events.job = job # save Bacula's job pointer
269 job.set_events(events) # register events desired
270 sys.stderr = events # send error output to Bacula
271 sys.stdout = events # send stdout to Bacula
272 jobid = job.JobId; client = job.Client
273 numvols = job.NumVols
274 job.JobReport="Python Dir JobStart: JobId=%d Client=%s NumVols=%d\n" % (jobid,client,numvols)
276 # Bacula Job is going to terminate
277 def JobEnd(self, job):
280 job.JobReport="Python Dir JobEnd output: JobId=%d Client=%s.\n" % (jobid, client)
282 # Called here when the Bacula daemon is going to exit
284 print "Daemon exiting."
286 bacula.set_events(BaculaEvents()) # register daemon events desired
289 These are the Job events that you can receive.
293 # Called here when you instantiate the Job. Not
298 # Called when the job is first scheduled
302 # Called just before running the job after initializing
303 # This is the point to change most Job parameters.
304 # It is equivalent to the JobRunBefore point.
307 def NewVolume(self, job):
311 volname = "TestA-001"
312 job.JobReport = "JobId=%d Client=%s NumVols=%d VolumeName=%s" % (jobid, client, numvol,volname)
313 job.JobReport="Python before New Volume set for Job.\n"
314 job.VolumeName=volname