5 \label{NewFeaturesChapter}
6 \index[general]{New Features}
8 This chapter presents the new features added to the development 2.5.x
9 versions to be released as Bacula version 3.0.0 near the end of 2008.
12 \index[general]{Accurate Backup}
13 As with most other backup programs, Bacula decides what files to backup
14 for Incremental and Differental backup by comparing the change (st\_ctime)
15 and modification (st\_mtime) times of the file to the time the last backup completed.
16 If one of those two times is later than the last backup time, then the file
17 will be backed up. This does not, however, permit tracking what files have
18 been deleted and will miss any file with an old time that may have been
19 restored or moved on the client filesystem.
21 If the {\bf Accurate = \lt{}yes|no\gt{}} directive is enabled (default no) in the
22 Job resource, the job will be run as an Accurate Job. For a {\bf Full}
23 backup, there is no difference, but for {\bf Differential} and {\bf Incremental}
24 backups, the Director will send a list of all previous files backed up, and the
25 File daemon will use that list to determine if any new files have been added or
26 or moved and if any files have been deleted. This allows Bacula to make an accurate
27 backup of your system to that point in time so that if you do a restore, it
28 will restore your system exactly. One note of caution about using Accurate backup is that
29 it requires more resources (CPU and memory) on both the Director and
30 the Client machines to create the list of previous files backed up, to send that
31 list to the File daemon, for the File daemon to keep the list (possibly very big)
32 in memory, and for the File daemon to do comparisons between every file in the
37 \index[general]{Copy Jobs}
38 A new {\bf Copy} job type has been implemented. It is essentially
39 identical to the existing Migration feature with the exception that
40 the Job that is copied is left unchanged. This essentially creates
41 two identical copies of the same backup. The Copy Job runs without
42 using the File daemon by copying the data from the old backup Volume to
43 a different Volume in a different Pool. See the Migration documentation
44 for additional details.
46 \section{Virtual Backup (Vbackup)}
47 \index[general]{Virtual Backup}
48 \index[general]{Vbackup}
50 Bacula's virtual backup feature is often called Synthetic Backup or
51 Consolidation in other backup products. It permits you to consolidate
52 the previous Full backup plus the most recent Differential backup and any
53 subsequent Incremental backups into a new Full backup. This is accomplished
54 without contacting the client by reading the previous backup data and
55 writing it to a volume in a different pool.
57 In some respects the Vbackup feature works similar to a Migration job, in
58 that Bacula normally reads the data from the pool specified in the
59 Job resource, and writes it to the {\bf Next Pool} specified in the
60 Job resource. The input Storage resource and the Output Storage resource
63 The Vbackup is enabled on a Job by Job in the Job resource by specifying
64 a level of {\bf VirtualFull}.
66 A typical Job resource definition might look like the following:
80 # Default pool definition
84 Recycle = yes # Automatically recycle Volumes
85 AutoPrune = yes # Prune expired volumes
86 Volume Retention = 365d # one year
94 Recycle = yes # Automatically recycle Volumes
95 AutoPrune = yes # Prune expired volumes
96 Volume Retention = 365d # one year
100 # Definition of file storage device
107 Maximum Concurrent Jobs = 5
110 # Definition of DDS Virtual tape disk storage device
113 Address = localhost # N.B. Use a fully qualified name here
116 Media Type = DiskChangerMedia
117 Maximum Concurrent Jobs = 4
122 Then in bconsole or via a Run schedule, you would run the job as:
125 run job=MyBackup level=Full
126 run job=MyBackup level=Incremental
127 run job=MyBackup level=Differential
128 run job=MyBackup level=Incremental
129 run job=MyBackup level=Incremental
132 So providing there were changes between each of those jobs, you would end up
133 with a Full backup, a Differential, which includes the first Incremental
134 backup, then two Incremental backups. All the above jobs would be written to
135 the {\bf Default} pool.
137 To consolidate those backups into a new Full backup, you would run the
141 run job=MyBackup level=VirtualFull
144 And it would produce a new Full backup without using the client, and the output
145 would be written to the {\bf Full} Pool which uses the Diskchanger Storage.
147 \section{Duplicate Job Control}
148 \index[general]{Duplicate Jobs}
149 The new version of Bacula provides four new directives that
150 give additional control over what Bacula does if duplicate jobs
151 are started. A duplicate job in the sense we use it here means
152 a second or subsequent job with the same name starts. This
153 happens most frequently when the first job runs longer than expected because no
156 The four directives each take as an argument a {\bf yes} or {\bf no} value and
157 are specified in the Job resource.
162 \item [Allow Duplicate Jobs = \lt{}yes|no\gt{}]
163 If this directive is enabled duplicate jobs will be run. If
164 the directive is set to {\bf no} (default) then only one job of a given name
165 may run at one time, and the action that Bacula takes to ensure only
166 one job runs is determined by the other directives (see below).
168 \item [Allow Higher Duplicates = \lt{}yes|no\gt{}]
169 If this directive is set to {\bf yes} (default) the job with a higher
170 priority (lower priority number) will be permitted to run. If the
171 priorities of the two jobs are the same, the outcome is determined by
172 other directives (see below).
174 \item [Cancel Queued Duplicates = \lt{}yes|no\gt{}]
175 If this directive is set to {\bf yes} (default) any job that is
176 already queued to run but not yet running will be canceled.
178 \item [Cancel Running Duplicates = \lt{}yes|no\gt{}]
179 If this directive is set to {\bf yes} any job that is already running
180 will be canceled. The default is {\bf no}.
183 \section{TLS Authentication}
184 \index[general]{TLS Authentication}
185 In Bacula version 2.5.x and later, in addition to the normal Bacula
186 CRAM-MD5 authentication that is used to authenticate each Bacula
187 connection, you can specify that you want TLS Authentication as well,
188 which will provide more secure authentication.
190 This new feature uses Bacula's existing TLS code (normally used for
191 communications encryption) to do authentication. To use it, you must
192 specify all the TLS directives normally used to enable communications
193 encryption (TLS Enable, TLS Verify Peer, TLS Certificate, ...) and
197 TLS Authenticate = yes
200 in the main daemon configuration resource (Director for the Director,
201 Client for the File daemon, and Storage for the Storage daemon).
203 When {\bf TLS Authenticate} is enabled, after doing the CRAM-MD5
204 authentication, Bacula will do the normal TLS authentication, then TLS
205 encryption will be turned off.
207 If you want to encrypt communications data, do not turn on {\bf TLS
210 \section{bextract non-portable Win32 data}
211 \index[general]{bextract handles Win32 non-portable data}
212 {\bf bextract} has been enhanced to be able to restore
213 non-portable Win32 data to any OS. Previous versions were
214 unable to restore non-portable Win32 data to machines that
215 did not have the Win32 BackupRead and BackupWrite API calls.
217 \section{State File updated at Job Termination}
218 \index[general]{State File}
219 In previous versions of Bacula, the state file, which provides a
220 summary of previous jobs run in the {\bf status} command output was
221 updated only when Bacula terminated, thus if the daemon crashed, the
222 state file might not contain all the run data. This version of
223 the Bacula daemons updates the state file on each job termination.
225 \section{MaxFullInterval}
226 \index[general]{MaxFullInterval}
227 The new Job resource directive {\bf Max Full Interval = \lt{}time-interval\gt{}}
228 can be used to specify the maximum time interval between {\bf Full} backup
229 jobs. When a job starts, if the time since the last Full backup is
230 greater than the specified interval, and the job would normally be an
231 {\bf Incremental} or {\bf Differential}, it will be automatically
232 upgraded to a {\bf Full} backup.
234 \section{MaxDiffInterval}
235 \index[general]{MaxDiffInterval}
236 The new Job resource directive {\bf Max Diff Interval = \lt{}time-interval\gt{}}
237 can be used to specify the maximum time interval between {\bf Differential} backup
238 jobs. When a job starts, if the time since the last Differential backup is
239 greater than the specified interval, and the job would normally be an
240 {\bf Incremental}, it will be automatically
241 upgraded to a {\bf Differential} backup.
243 \section{No Dump Flag}
244 \index[general]{MaxDiffInterval}
245 On FreeBSD systems, each file has a {\bf no dump flag} that can be set
246 by the user, and when it is set it is an indication to backup programs
247 to not backup that particular file. This version of Bacula contains a
248 new Options directive within a FileSet resource, which instructs Bacula to
249 obey this flag. The new directive is:
252 Honor No Dump Flag = yes|no
255 The default value is {\bf no}.
259 \index[general]{IgnoreDir}
260 The {\bf Ignore Dir = \lt{}filename\gt{}} is a new directive that can be added to the Include
261 section of the FileSet resource. If the specified
262 filename is found on the Client in any directory to be backed up,
263 the whole directory will be ignored (not backed up).
267 # List of files to be backed up
275 IgnoreDir = .excludeme
280 But in /home, there may be hundreds of directories of users and some
281 people want to indicate that they don't want to have certain
282 directories backed up. For example, with the above FileSet, if
283 the user or sysadmin creates a file named {\bf .excludeme} in
284 specific directories, such as
287 /home/user/www/cache/.excludeme
288 /home/user/temp/.excludeme
291 then Bacula will not backup the two directories named:
301 \section{Bacula Plugins}
302 \index[general]{Plugin}
303 Support for shared object plugins has been implemented in the Linux
304 (and Unix) File daemon. The API will be documented separately in
305 the Developer's Guide or in a new document. For the moment, there is
306 a single plugin named {\bf bpipe} that allows an external program to
307 get control to backup and restore a file.
309 Plugins are also planned (partially implemented) in the Director and the
310 Storage daemon. The code is also implemented to work on Win32 machines,
311 but it has not yet been tested.
313 \subsection{Plugin Directory}
314 Each daemon (DIR, FD, SD) has a new {\bf Plugin Directory} directive that may
315 be added to the daemon definition resource. The directory takes a quoted
316 string argument, which is the name of the directory in which the daemon can
317 find the Bacula plugins. If this directive is not specified, Bacula will not
318 load any plugins. Since each plugin has a distinctive name, all the daemons
319 can share the same plugin directory.
323 \subsection{Plugin Options}
324 The {\bf Plugin Options} directive takes a quoted string
325 arguement (after the equal sign) and may be specified in the
326 Job resource. The options specified will be passed to the plugin
327 when it is run. The value defined in the Job resource can be modified
328 by the user when he runs a Job via the {\bf bconsole} command line
331 Note: this directive may be specified, but it is not yet passed to
332 the plugin (i.e. not fully implemented).
334 \subsection{Plugin Options ACL}
335 The {\bf Plugin Options ACL} directive may be specified in the
336 Director's Console resource. It functions as all the other ACL commands
337 do by permitting users running restricted consoles to specify a
338 {\bf Plugin Options} that overrides the one specified in the Job
339 definition. Without this directive restricted consoles may not modify
343 The {\bf Plugin} directive is specified in the Include section of
344 a FileSet resource where you put your {\bf File = xxx} directives.
360 In the above example, when the File daemon is processing the directives
361 in the Include section, it will first backup all the files in {\bf /home}
362 then it will load the plugin named {\bf bpipe} (actually bpipe-dir.so) from
363 the Plugin Directory. The syntax and semantics of the Plugin directive
364 require the first part of the string up to the colon (:) to be the name
365 of the plugin. Everything after the first colon is ignored by the File daemon but
366 is passed to the plugin. Thus the plugin writer may define the meaning of the
367 rest of the string as he wishes.
369 Please see the next section for information about the {\bf bpipe} Bacula
372 \section{The bpipe Plugin}
373 The {\bf bpipe} plugin is provided in the directory src/plugins/fd/bpipe-fd.c of
374 the Bacula source distribution. When the plugin is compiled and linking into
375 the resulting dynamic shared object (DSO), it will have the name {\bf bpipe-fd.so}.
377 The purpose of the plugin is to provide an interface to any system program for
378 backup and restore. As specified above the {\bf bpipe} plugin is specified in
379 the Include section of your Job's FileSet resource. The full syntax of the
380 plugin directive as interpreted by the {\bf bpipe} plugin (each plugin is free
381 to specify the sytax as it wishes) is:
384 Plugin = "<field1>:<field2>:<field3>:<field4>"
389 \item {\bf field1} is the name of the plugin with the trailing {\bf -fd.so}
390 stripped off, so in this case, we would put {\bf bpipe} in this field.
392 \item {\bf field2} specifies the namespace, which for {\bf bpipe} is the
393 pseudo path and filename under which the backup will be saved. This pseudo
394 path and filename will be seen by the user in the restore file tree.
395 For example, if the value is {\bf /MYSQL/regress.sql}, the data
396 backed up by the plugin will be put under that "pseudo" path and filename.
397 You must be careful to choose a naming convention that is unique to avoid
398 a conflict with a path and filename that actually exists on your system.
400 \item {\bf field3} for the {\bf bpipe} plugin
401 specifies the "reader" program that is called by the plugin during
402 backup to read the data. {\bf bpipe} will call this program by doing a
405 \item {\bf field4} for the {\bf bpipe} plugin
406 specifies the "writer" program that is called by the plugin during
407 restore to write the data back to the filesystem.
410 Putting it all together, the full plugin directive line might look
414 Plugin = "bpipe:/MYSQL/regress.sql:mysqldump -f
415 --opt --databases bacula:mysql"
418 The directive has been split into two lines, but within the {\bf bacula-dir.conf} file
419 would be written on a single line.
421 This causes the File daemon to call the {\bf bpipe} plugin, which will write
422 its data into the "pseudo" file {\bf /MYSQL/regress.sql} by calling the
423 program {\bf mysqldump -f --opt --database bacula} to read the data during
424 backup. The mysqldump command outputs all the data for the database named
425 {\bf bacula}, which will be read by the plugin and stored in the backup.
426 During restore, the data that was backed up will be sent to the program
427 specified in the last field, which in this case is {\bf mysql}. When
428 {\bf mysql} is called, it will read the data sent to it by the plugn
429 then write it back to the same database from which it came ({\bf bacula}
432 The {\bf bpipe} plugin is a generic pipe program, that simply transmits
433 the data from a specified program to Bacula for backup, and then from Bacula to
434 a specified program for restore.
436 By using different command lines to {\bf bpipe},
437 you can backup any kind of data (ASCII or binary) depending
438 on the program called.
442 \section{Display Autochanger Content}
443 \index[general]{StatusSlots}
445 The {\bf status slots storage=\lt{}storage-name\gt{}} command displays autochanger content.
449 Slot | Volume Name | Status | Media Type | Pool | Loaded |
450 ------+---------------+----------+-------------------+------------+---------|
451 1 | 00001 | Append | DiskChangerMedia | Default | 0 |
452 2 | 00002 | Append | DiskChangerMedia | Default | 0 |
453 3*| 00003 | Append | DiskChangerMedia | Scratch | 0 |
458 If you an asterisk ({\bf *}) appears after the slot number, you must run an {\bf update slots}
459 command to synchronize autochanger content with your catalog.
461 \section{Miscellaneous}
462 \index[general]{Misc New Features}
464 \item [Virtual Tape Emulation]
466 We now have a Virtual Tape emulator that allows us to run though 99.9\% of
467 the tape code but actually reading and writing to a disk file. Used with the
468 \textbf{disk-changer} script, you can now emulate an autochanger with 10 drives
469 and 700 slots. This feature is most useful in testing. It is enabled
470 by using {\bf Device Type = vtape} in the Storage daemon's Device
471 directive. This feature is only implemented on Linux machines.
473 \item [Bat Enhancements]
474 Bat (the Bacula Administration Tool) GUI program has been significantly
475 enhanced and stabilized. In particular, there are new table based status
476 commands; it can now be easily localized using Qt4 Linguist.
478 The Bat communications protocol has been significantly enhanced to improve
481 \item [RunScript Enhancements]
482 The {\bf RunScript} resource has been enhanced to permit multiple
483 commands per RunScript. Simply specify multiple {\bf Command} directives
490 Command = "/bin/echo test"
491 Command = "/bin/echo an other test"
492 Command = "/bin/echo 3 commands in the same runscript"
499 A new Client RunScript {\bf RunsWhen} keyword of {\bf AfterVSS} has been implemented, which
500 runs the command after the Volume Shadow Copy has been made.
502 Console commands can be specified within a RunScript by using:
503 {\bf Console = \lt{}command\gt{}}, however, this command has not been
504 carefully tested and debugged and is known to easily crash the Director.
505 We would appreciate feedback. Due to the recursive nature of this command, we
506 may remove it before the final release.
508 \item [Status Enhancements]
509 The bconsole {\bf status dir} output has been enhanced to indicate
510 Storage daemon job spooling and despooling activity.
512 \item [Connect Timeout]
513 The default connect timeout to the File
514 daemon has been set to 3 minutes. Previously it was 30 minutes.
516 \item [ftruncate for NFS Volumes]
517 If you write to a Volume mounted by NFS (say on a local file server),
518 in previous Bacula versions, when the Volume was recycled, it was not
519 properly truncated because NFS does not implement ftruncate (file
520 truncate). This is now corrected in the new version because we have
521 written code (actually a kind user) that deletes and recreates the Volume,
522 thus accomplishing the same thing as a truncate.
524 \item [Support for Ubuntu]
525 The new version of Bacula now recognizes the Ubuntu (and Kubuntu)
526 version of Linux, and thus now provides correct autostart routines.
527 Since Ubuntu officially supports Bacula, you can also obtain any
528 recent release of Bacula from the Ubuntu repositories.
532 The File daemon to Director protocol now includes a version
533 number, which will help us in future versions automatically determine
534 if a File daemon is not compatible.
536 \item [Max Run Sched Time]
538 \item [Full Max Wait Time]
540 \item [Incremental Max Wait Time]
542 \item [Differential Max Wait Time]
544 \item [Full Max Run Time]
546 \item [Differential Max Run Time]
548 \item [Incremental Max Run Time]
551 \item [Statistics Enhancements]
552 If you (or your boss) want to have statistics on your backups, you could use
553 a few SQL queries on the Job table to report how many:
556 \item jobs have been successful
557 \item files have been backed up
561 However, these statistics are accurate only if your job retention is greater than
562 your statistics period. Ie, if jobs are purged from the catalog, you won't be
565 Now, you can use the \textbf{update stats [days=num]} console command to fill the
566 JobStat table with new Job records.
568 The \textbf{Statistics Retention = \lt{}time\gt{}} director directive defines
569 the length of time that Bacula will keep statistics job records in the Catalog
570 database after the Job End time. (In \texttt{JobStat} table) When this time
571 period expires, and if user runs \texttt{prune stats} command, Bacula will
572 prune (remove) Job records that are older than the specified period.
574 These statistics records aren't used for restore purpose, but mainly for
575 capacity planning, billings, etc.
577 You can use the following Job resource in your nightly \textbf{BackupCatalog} job to maintain
584 Console = "update stats days=3"
585 Console = "prune stats yes"
592 \item [Spooling Enhancements]
593 A new job directive permits to specify the spool size per job. This is used
594 in advanced job tunning. {\bf SpoolSize={\it bytes}}
598 \section{Building Bacula Plugins}
599 There is currently one sample program {\bf example-plugin-fd.c} and
600 one working plugin {\bf bpipe-fd.c} that can be found in the Bacula
601 {\bf src/plugins/fd} directory. Both are built with the following:
605 ./configure <your-options>
613 After building Bacula and changing into the src/plugins/fd directory,
614 the {\bf make} command will build the {\bf bpipe-fd.so} plugin, which
615 is a very useful and working program.
617 The {\bf make test} command will build the {\bf example-plugin-fd.so}
618 plugin and a binary named main, which is build from the source
619 code located in {\bf src/filed/fd\_plugins.c}.
621 If you execute {\bf ./main}, it will load and run the example-plugin-fd
622 plugin simulating a small number of the calling sequences that Bacula uses
623 in calling a real plugin. This allows you to do initial testing of
624 your plugin prior to trying it with Bacula.
626 You can get a good idea of how to write your own plugin by first
627 studying the example-plugin-fd, and actually running it. Then
628 it can also be instructive to read the bpipe-fd.c code as it is
629 a real plugin, which is still rather simple and small.
631 When actually writing your own plugin, you may use the example-plugin-fd.c
632 code as a template for your code.
634 \section{Bacula FD Plugin API}
635 To write a Bacula plugin, you cread a dynamic shared object
636 program (or dll on Win32) with a particular name and two
637 entry points, place it in the {\bf Plugins Directory}, and when the FD
638 starts, it will load all the plugins found in that directory.
639 Once it loads them, it calls the {\bf loadPlugin} entry point (see below)
640 then later, it will call particular functions that are defined by the
641 {\bf loadPlugin} interface. When Bacula is finished with the plugin
642 (when Bacula is going to exit), it will call the {\bf unloadPlugin}
645 The two entry points are:
648 bRC loadPlugin(bInfo *lbinfo, bFuncs *lbfuncs, pInfo **pinfo, pFuncs **pfuncs)
655 both these entry points to the shared object are defined as C entry points
656 to avoid name mangling complications with C++. However, the shared object
657 can actually be written in any language.
659 The definitions for {\bf bRC} and the arguments are {\bf
660 src/filed/fd-plugins.h} and so this header file needs to be included in
661 your plug. It along with {\bf lib/plugins.h} define basically the whole
662 plugin interface. Within this header file, it includes the fillowing
666 #include <sys/types.h>
668 #include "bc_types.h"
669 #include "lib/plugins.h"
670 #include <sys/stat.h>
673 Aside from the {\bf bc\_types.h} header, the plugin definition uses the
674 minimum code from Bacula. The bc\_types.h file is required to ensure that
675 the data type defintions in arguments correspond to the Bacula core code.
677 At a future point in time, we hope to make the Bacula libbac.a into a
678 shared object so that the plugin can use much more of Bacula's
679 infrastructure, but for this first cut, we have tried to minimize the
680 dependence on Bacula.
682 \subsection{loadPlugin}
683 As previously mentioned, the {\bf loadPlugin} entry point in the plugin
684 is called immediately after Bacula loads the plugin. In calling the
685 plugin, the first two arguments are information from Bacula that
686 is passed to the plugin, and the last two arguments are information
687 about the plugin that is returned to Bacula. The call is:
690 bRC loadPlugin(bInfo *lbinfo, bFuncs *lbfuncs, pInfo **pinfo, pFuncs **pfuncs)
693 and the arguments are:
697 This is information about Bacula in general. Currently, the only value
698 defined in the bInfo structure is version, which is the Bacula plugin
699 interface version, currently defined as 1.
700 The exact definition as of this writing is:
703 typedef struct s_baculaInfo {
710 The bFuncs structure defines the callback entry points within Bacula
711 that the plugin can use register events, get Bacula values, set
712 Bacula values, and send messages to the Job output.
714 The exact definition as of this writing is:
717 ypedef struct s_baculaFuncs {
720 bRC (*registerBaculaEvents)(bpContext *ctx, ...);
721 bRC (*getBaculaValue)(bpContext *ctx, bVariable var, void *value);
722 bRC (*setBaculaValue)(bpContext *ctx, bVariable var, void *value);
723 bRC (*JobMessage)(bpContext *ctx, const char *file, int line,
724 int type, time_t mtime, const char *fmt, ...);
725 bRC (*DebugMessage)(bpContext *ctx, const char *file, int line,
726 int level, const char *fmt, ...);
730 We will discuss these entry points and how to use them a bit later when
731 describing the plugin code.
734 When the loadPlugin entry point is called, the plugin must initialize
735 an information structure about the plugin and return a pointer to
736 this structure to Bacula.
738 The exact definition as of this writing is:
741 typedef struct s_pluginInfo {
744 const char *plugin_magic;
745 const char *plugin_license;
746 const char *plugin_author;
747 const char *plugin_date;
748 const char *plugin_version;
749 const char *plugin_description;
755 \item [version] is the current plugin interface version, currently
757 \item [plugin\_magic] is a pointer to the string "*FDPluginData*", a
758 sort of sanity check.
759 \item [plugin\_license] is a pointer to a string that describes the
761 \item [plugin\_author] is a pointer to the name of the author of the program.
762 \item [plugin\_date] is the pointer string containing the date of the plugin.
763 \item [plugin\_version] is a pointer to a string containing the version of
765 \item [plugin\_description] is a pointer to a string describing what the
769 The pInfo structure must be defined in static memory because Bacula does not
770 copy it and may refer to the values at any time while the plugin is
774 When the loadPlugin entry point is called, the plugin must initialize
775 an entry point structure about the plugin and return a pointer to
776 this structure to Bacula. This structure contains pointer to each
777 of the entry points that the plugin must provide for Bacula. When
778 Bacula is actually running the plugin, it will call the defined
779 entry points at particular times. All entry points must be defined.
781 The pFuncs structure must be defined in static memory because Bacula does not
782 copy it and may refer to the values at any time while the plugin is
786 The exact definition as of this writing is:
789 typedef struct s_pluginFuncs {
792 bRC (*newPlugin)(bpContext *ctx);
793 bRC (*freePlugin)(bpContext *ctx);
794 bRC (*getPluginValue)(bpContext *ctx, pVariable var, void *value);
795 bRC (*setPluginValue)(bpContext *ctx, pVariable var, void *value);
796 bRC (*handlePluginEvent)(bpContext *ctx, bEvent *event, void *value);
797 bRC (*startBackupFile)(bpContext *ctx, struct save_pkt *sp);
798 bRC (*endBackupFile)(bpContext *ctx);
799 bRC (*startRestoreFile)(bpContext *ctx, const char *cmd);
800 bRC (*endRestoreFile)(bpContext *ctx);
801 bRC (*pluginIO)(bpContext *ctx, struct io_pkt *io);
802 bRC (*createFile)(bpContext *ctx, struct restore_pkt *rp);
803 bRC (*setFileAttributes)(bpContext *ctx, struct restore_pkt *rp);
809 \item [size] is the size of the structure.
810 \item [version] is the plugin interface version.
811 \item [newPlugin] is the entry point that Bacula will call
812 when a new instance of the plugin is created. This typically
813 happens at the beginning of a Job. If 10 Jobs are running
814 simultaneously, there will be at least 10 instances of the
817 The bpContext structure will be passed to the plugin, and
818 during this call, if the plugin needs to have any private
819 working storage that is associated with the particular
820 instance of the plugin, it should create it from the heap
821 (malloc the memory). The plugin then puts a pointer to
822 its private working storage in the {\bf pContext} variable.
825 typedef struct s_bpContext {
826 void *pContext; /* Plugin private context */
827 void *bContext; /* Bacula private context */
832 This context pointer will be passed as the first argument to all
833 the entry points that Bacula can call within the plugin. Needless
834 to say, the plugin should not change the bContext variable, which
835 is Bacula's private context pointer for this instance of this
838 \item [freePlugin] this entry point is called when the
839 this instance of the plugin is no longer needed (the Job is
840 ending), and the plugin should release any memory it may
841 have allocated for the pContext.
843 \item [getPluginValue] Bacula will call this entry point to get
844 a value from the plugin. This entry point is currently not called.
846 \item [setPluginValue] Bacula will call this entry point to set
847 a value in the plugin. This entry point is currently not called.
849 \item [handlePluginEvent] This entry point is called when Bacula
850 encounters certain events. Bacula passes the pointer to an event
851 structure (bEvent), which currently has one item, the eventType:
854 typedef struct s_bEvent {
859 which defines what event has been triggered, and for each event,
860 Bacula will pass a pointer to a value associated with that event.
861 If no value is associated with a particular event, Bacula will
862 pass a NULL pointer, so you must always check for it.
864 The current list of events are:
870 bEventStartBackupJob = 3,
871 bEventEndBackupJob = 4,
872 bEventStartRestoreJob = 5,
873 bEventEndRestoreJob = 6,
874 bEventStartVerifyJob = 7,
875 bEventEndVerifyJob = 8,
876 bEventBackupCommand = 9,
877 bEventRestoreCommand = 10,
884 Most of which are pretty explanatory.