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:--:with-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} Directive defined, if so, it looks in that directory for
37 a file named {\bf DirStartUp.py}. If it is found, Bacula will pass this
38 file to Python for execution. The {\bf Scripts Directory} is a new
39 directive that you add to the Director resource of your bacula-dir.conf
42 \subsection*{Bacula Events}
43 \index[general]{Bacula Events}
44 \index[general]{Events}
45 \addcontentsline{toc}{subsection}{Bacula Events}
46 A Bacula event is a point in the Bacula code where Bacula
47 will call a subroutine (actually a method) that you have
48 defined in the Python StartUp script. Events correspond
49 to some significant event such as a Job Start, a Job End,
50 Bacula needs a new Volume Name, ... When your script is
51 called, it will have access to all the Bacula variables
52 specific to the Job (attributes of the Job Object), and
53 it can even call some of the Job methods (subroutines)
54 or set new values in the Job attributes, such as the
55 Priority. You will see below how the events are used.
57 \subsection*{Python Objects}
58 \index[general]{Python Objects}
59 \index[general]{Objects!Python}
60 \addcontentsline{toc}{subsection}{Python Objects}
62 There are four Python objects that you will need to work with:
64 \item [The Bacula Object]
65 The Bacula object is created by the Bacula daemon (the Director
66 in the present case) when the daemon starts. It is available to
67 the Python startup script, {\bf DirStartup.py}, by importing the
68 Bacula definitions with {\bf import bacula}. The methods
69 available with this object are described below.
71 \item [The Bacula Events Class]
72 You create this class in the startup script, and you pass
73 it to the Bacula Object's {\bf set_events} method. The
74 purpose of the Bacula Events Class is to define what global
75 or daemon events you want to monitor. When one of those events
76 occurs, your Bacula Events Class will be called at the method
77 corresponding to the event. There are currently three events,
78 JobStart, JobEnd, and Exit, which are described in detail below.
80 \item [The Job Object]
81 When a Job starts, and assuming you have defined a JobStart method
82 in your Bacula Events Class, Bacula will create a Job Object. This
83 object will be passed to the JobStart event. The Job Object has a
84 has good number of read-only members or attributes providing many
85 details of the Job, and it also has a number of writable attributes
86 that allow you to pass information into the Job. These attributes
89 \item [The Job Events Class]
90 You create this class in the JobStart method of your Bacula Events
91 class, and it allows you to define which of the possible Job Object
92 events you want to see. You must pass an instance of your Job Events
93 class to the Job Object set_events() method.
94 Normally, you will probably only have one
95 Job Events Class, which will be instantiated for each Job. However,
96 if you wish to see different events in different Jobs, you may have
97 as many Job Events classes as you wish.
101 The first thing the startup script must do is to define what global Bacula
102 events (daemon events), it wants to see. This is done by creating a
103 Bacula Events class, instantiating it, then passing it to the
104 {\bf set_events} method. There are three possible
109 \index[dir]{JobStart}
110 This Python method, if defined, will be called each time a Job is started.
111 The method is passed the class instantiation object as the first argument,
112 and the Bacula Job object as the second argument. The Bacula Job object
113 has several built-in methods, and you can define which ones you
114 want called. If you do not define this method, you will not be able
115 to interact with Bacula jobs.
118 This Python method, if defined, will be called each time a Job terminates.
119 The method is passed the class instantiation object as the first argument,
120 and the Bacula Job object as the second argument.
123 This Python method, if defined, will be called when the Director terminates.
124 The method is passed the class instantiation object as the first argument.
127 Access to the Bacula variables and methods is done with:
131 A simple definition of the Bacula Events Class might be the following:
137 def JobStart(self, job):
142 Then to instantiate the class and pass it to Bacula, you
147 bacula.set_events(BaculaEvents()) # register Bacula Events wanted
151 And at that point, each time a Job is started, your BaculaEvents JobStart
152 method will be called.
154 Now to actually do anything with a Job, you must define which Job events
155 you want to see, and this is done by defining a JobEvents class containing
156 the methods you want called. Each method name corresponds to one of the
157 Job Events that Bacula will generate.
159 A simple Job Events class might look like the following:
164 def NewVolume(self, job):
169 Here, your JobEvents class method NewVolume will be called each time
170 the Job needs a new Volume name. To actually register the events defined
171 in your class with the Job, you must instantiate the JobEvents class and
172 set it in the Job {\be set_events} variable. Note, this is a bit different
173 from how you registered the Bacula events. The registration process must
174 be done in the Bacula JobStart event (your method). So, you would modify
175 Bacula Events (not the Job events) as follows:
181 def JobStart(self, job):
182 events = JobEvents() # create instance of Job class
183 job.set_events(events) # register Job events desired
188 The following are the methods (subroutines) provided within the
189 directory by the {\bf job} object.
191 \item [set_events] The set_events takes a single
192 argument, which is the instantation of the Job Events class
193 that contains the methods that you want called. The method
194 names that will be called must correspond to the Bacula
195 defined events. You may define additional methods but Bacula
197 \item [run] The run method takes a single string
198 argument, which is the run command (same as in the Console)
199 that you want to submit to start a new Job. The value
200 returned by the run method is the JobId of the job that
201 started, or -1 if there was an error.
202 \item [write] The write method is used to be able to send
203 print output to the Job Report. This will be described later.
204 \item [DoesVolumeExist] The DoesVolumeExist takes a single
205 string argument, which is the Volume name, and returns
206 1 if the volume exists in the Catalog and 0 if the volume
210 The following attributes are read/write within the Director
211 for the {\bf job} object.
214 \item [Priority] Read or set the Job priority.
215 Note, that setting a Job Priority is effective only before
216 the Job actually starts. (not functional yet)
219 The following read-only attributes are available within the Director
220 for the {\bf job} object.
223 \item [DirName] The name of the Director daemon.
237 \item [Version] tuple consisting of (Version, Build-date)
238 \item [CatalogRes] tuple consisting of (DBName, Address, User,
239 Password, Socket, Port, Database Vendor) taken from the Catalog resource
240 for the Job with the exception of Database Vendor, which is
241 one of the following: MySQL, PostgreSQL, SQLite, Internal,
242 depending on what database you configured.
245 The following write-only attributes are available within the
249 \item [JobReport] Send line to the Job Report.
250 \item [VolumeName] Set a new Volume name. Valid only during the
254 \subsection*{Python Console Command}
255 \index[general]{Python Console Command}
256 \index[general]{Console Command!Python}
257 \addcontentsline{toc}{subsection}{Python Console Command}
259 There is a new Console command named {\bf python}. It takes
260 a single argument {\bf restart}. Example:
265 This command restarts the Python interpreter in the Director.
266 This can be useful when you are modifying the DirStartUp script,
267 because normally Python will cache it, and thus the
268 script will be read one time.
271 \subsection*{Python Example}
272 \index[general]{Python Example}
273 \index[general]{Example!Python}
274 \addcontentsline{toc}{subsection}{Python Example}
276 An example script for the Director startup file is provided in
277 {\bf examples/python/DirStartup.py} as follows:
282 # Bacula Python interface script for the Director
285 # You must import both sys and bacula
288 # This is the list of Bacula daemon events that you
292 # Called here when a new Bacula Events class is
293 # is created. Normally not used
296 def JobStart(self, job):
298 Called here when a new job is started. If you want
299 to do anything with the Job, you must register
300 events you want to receive.
302 events = JobEvents() # create instance of Job class
303 events.job = job # save Bacula's job pointer
304 job.set_events(events) # register events desired
305 sys.stderr = events # send error output to Bacula
306 sys.stdout = events # send stdout to Bacula
307 jobid = job.JobId; client = job.Client
308 numvols = job.NumVols
309 job.JobReport="Python Dir JobStart: JobId=%d Client=%s NumVols=%d\n" % (jobid,client,numvols)
311 # Bacula Job is going to terminate
312 def JobEnd(self, job):
315 job.JobReport="Python Dir JobEnd output: JobId=%d Client=%s.\n" % (jobid, client)
317 # Called here when the Bacula daemon is going to exit
319 print "Daemon exiting."
321 bacula.set_events(BaculaEvents()) # register daemon events desired
324 These are the Job events that you can receive.
328 # Called here when you instantiate the Job. Not
333 # Called when the job is first scheduled
337 # Called just before running the job after initializing
338 # This is the point to change most Job parameters.
339 # It is equivalent to the JobRunBefore point.
342 def NewVolume(self, job):
346 volname = "TestA-001"
347 job.JobReport = "JobId=%d Client=%s NumVols=%d VolumeName=%s" % (jobid, client, numvol,volname)
348 job.JobReport="Python before New Volume set for Job.\n"
349 job.VolumeName=volname