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.
638 \chapter{Bacula FD Plugin API}
639 To write a Bacula plugin, you cread a dynamic shared object
640 program (or dll on Win32) with a particular name and two
641 entry points, place it in the {\bf Plugins Directory}, and when the FD
642 starts, it will load all the plugins found in that directory.
643 Once it loads them, it calls the {\bf loadPlugin} entry point (see below)
644 then later, it will call particular functions that are defined by the
645 {\bf loadPlugin} interface. When Bacula is finished with the plugin
646 (when Bacula is going to exit), it will call the {\bf unloadPlugin}
649 The two entry points are:
652 bRC loadPlugin(bInfo *lbinfo, bFuncs *lbfuncs, pInfo **pinfo, pFuncs **pfuncs)
659 both these entry points to the shared object are defined as C entry points
660 to avoid name mangling complications with C++. However, the shared object
661 can actually be written in any language.
663 The definitions for {\bf bRC} and the arguments are {\bf
664 src/filed/fd-plugins.h} and so this header file needs to be included in
665 your plug. It along with {\bf lib/plugins.h} define basically the whole
666 plugin interface. Within this header file, it includes the fillowing
670 #include <sys/types.h>
672 #include "bc_types.h"
673 #include "lib/plugins.h"
674 #include <sys/stat.h>
677 Aside from the {\bf bc\_types.h} header, the plugin definition uses the
678 minimum code from Bacula. The bc\_types.h file is required to ensure that
679 the data type defintions in arguments correspond to the Bacula core code.
681 At a future point in time, we hope to make the Bacula libbac.a into a
682 shared object so that the plugin can use much more of Bacula's
683 infrastructure, but for this first cut, we have tried to minimize the
684 dependence on Bacula.
687 As previously mentioned, the {\bf loadPlugin} entry point in the plugin
688 is called immediately after Bacula loads the plugin. In calling the
689 plugin, the first two arguments are information from Bacula that
690 is passed to the plugin, and the last two arguments are information
691 about the plugin that is returned to Bacula. The call is:
694 bRC loadPlugin(bInfo *lbinfo, bFuncs *lbfuncs, pInfo **pinfo, pFuncs **pfuncs)
697 and the arguments are:
701 This is information about Bacula in general. Currently, the only value
702 defined in the bInfo structure is version, which is the Bacula plugin
703 interface version, currently defined as 1.
704 The exact definition as of this writing is:
707 typedef struct s_baculaInfo {
714 The bFuncs structure defines the callback entry points within Bacula
715 that the plugin can use register events, get Bacula values, set
716 Bacula values, and send messages to the Job output.
718 The exact definition as of this writing is:
721 ypedef struct s_baculaFuncs {
724 bRC (*registerBaculaEvents)(bpContext *ctx, ...);
725 bRC (*getBaculaValue)(bpContext *ctx, bVariable var, void *value);
726 bRC (*setBaculaValue)(bpContext *ctx, bVariable var, void *value);
727 bRC (*JobMessage)(bpContext *ctx, const char *file, int line,
728 int type, time_t mtime, const char *fmt, ...);
729 bRC (*DebugMessage)(bpContext *ctx, const char *file, int line,
730 int level, const char *fmt, ...);
734 We will discuss these entry points and how to use them a bit later when
735 describing the plugin code.
738 When the loadPlugin entry point is called, the plugin must initialize
739 an information structure about the plugin and return a pointer to
740 this structure to Bacula.
742 The exact definition as of this writing is:
745 typedef struct s_pluginInfo {
748 const char *plugin_magic;
749 const char *plugin_license;
750 const char *plugin_author;
751 const char *plugin_date;
752 const char *plugin_version;
753 const char *plugin_description;
759 \item [version] is the current plugin interface version, currently
761 \item [plugin\_magic] is a pointer to the string "*FDPluginData*", a
762 sort of sanity check.
763 \item [plugin\_license] is a pointer to a string that describes the
765 \item [plugin\_author] is a pointer to the name of the author of the program.
766 \item [plugin\_date] is the pointer string containing the date of the plugin.
767 \item [plugin\_version] is a pointer to a string containing the version of
769 \item [plugin\_description] is a pointer to a string describing what the
773 The pInfo structure must be defined in static memory because Bacula does not
774 copy it and may refer to the values at any time while the plugin is
778 When the loadPlugin entry point is called, the plugin must initialize
779 an entry point structure about the plugin and return a pointer to
780 this structure to Bacula. This structure contains pointer to each
781 of the entry points that the plugin must provide for Bacula. When
782 Bacula is actually running the plugin, it will call the defined
783 entry points at particular times. All entry points must be defined.
785 The pFuncs structure must be defined in static memory because Bacula does not
786 copy it and may refer to the values at any time while the plugin is
790 The exact definition as of this writing is:
793 typedef struct s_pluginFuncs {
796 bRC (*newPlugin)(bpContext *ctx);
797 bRC (*freePlugin)(bpContext *ctx);
798 bRC (*getPluginValue)(bpContext *ctx, pVariable var, void *value);
799 bRC (*setPluginValue)(bpContext *ctx, pVariable var, void *value);
800 bRC (*handlePluginEvent)(bpContext *ctx, bEvent *event, void *value);
801 bRC (*startBackupFile)(bpContext *ctx, struct save_pkt *sp);
802 bRC (*endBackupFile)(bpContext *ctx);
803 bRC (*startRestoreFile)(bpContext *ctx, const char *cmd);
804 bRC (*endRestoreFile)(bpContext *ctx);
805 bRC (*pluginIO)(bpContext *ctx, struct io_pkt *io);
806 bRC (*createFile)(bpContext *ctx, struct restore_pkt *rp);
807 bRC (*setFileAttributes)(bpContext *ctx, struct restore_pkt *rp);
811 The details of the entry points will be presented in
812 separate sections below.
816 \item [size] is the size of the structure.
817 \item [version] is the plugin interface version.
822 \section{Plugin Entry Points}
823 This section will describe each of the entry points that
824 the plugin must provide for Bacula, when they are called
827 \subsection{newPlugin(bpContext *ctx)}
828 This is the entry point that Bacula will call
829 when a new instance of the plugin is created. This typically
830 happens at the beginning of a Job. If 10 Jobs are running
831 simultaneously, there will be at least 10 instances of the
834 The bpContext structure will be passed to the plugin, and
835 during this call, if the plugin needs to have any private
836 working storage that is associated with the particular
837 instance of the plugin, it should create it from the heap
838 (malloc the memory). The plugin then puts a pointer to
839 its private working storage in the {\bf pContext} variable.
842 typedef struct s_bpContext {
843 void *pContext; /* Plugin private context */
844 void *bContext; /* Bacula private context */
849 This context pointer will be passed as the first argument to all
850 the entry points that Bacula can call within the plugin. Needless
851 to say, the plugin should not change the bContext variable, which
852 is Bacula's private context pointer for this instance of this
855 \subsection{freePlugin(bpContext *ctx)}
856 This entry point is called when the
857 this instance of the plugin is no longer needed (the Job is
858 ending), and the plugin should release any memory it may
859 have allocated for the pContext.
861 \subsection{getPluginValue(bpContext *ctx, pVariable var, void *value)}
862 Bacula will call this entry point to get
863 a value from the plugin. This entry point is currently not called.
865 \subsection{setPluginValue(bpContext *ctx, pVariable var, void *value)}
866 Bacula will call this entry point to set
867 a value in the plugin. This entry point is currently not called.
869 \subsection{handlePluginEvent(bpContext *ctx, bEvent *event, void *value)}
870 This entry point is called when Bacula
871 encounters certain events. Bacula passes the pointer to an event
872 structure (bEvent), which currently has one item, the eventType:
875 typedef struct s_bEvent {
880 which defines what event has been triggered, and for each event,
881 Bacula will pass a pointer to a value associated with that event.
882 If no value is associated with a particular event, Bacula will
883 pass a NULL pointer, so you must always check for it.
885 The current list of events are:
891 bEventStartBackupJob = 3,
892 bEventEndBackupJob = 4,
893 bEventStartRestoreJob = 5,
894 bEventEndRestoreJob = 6,
895 bEventStartVerifyJob = 7,
896 bEventEndVerifyJob = 8,
897 bEventBackupCommand = 9,
898 bEventRestoreCommand = 10,
905 Most of which are pretty explanatory.
908 \item [bEventJobStart] is called whenever a Job starts.
909 \item [bEventJobEnd] is called whenever a Job ends.
910 \item [bEventStartBackupJob] is called when a Backup Job begins.
911 \item [bEventEndBackupJob] is called when a Backup Job ends.
912 \item [bEventStartRestoreJob] is called when a Restore Job starts.
913 \item [bEventEndRestoreJob] is called when a Restore Job ends.
914 \item [bEventStartVerifyJob] is called when a Verify Job starts.
915 \item [bEventEndVerifyJob] is called when a Verify Job ends.
916 \item [bEventBackupCommand]
917 \item [bEventRestoreCommand]
918 \item [bEventLevel] is called when the level is set for a new Job.
919 \item [bEventSince] is called whent the since time is set for a new Job.
922 \subsection{startBackupFile(bpContext *ctx, struct save\_pkt *sp)}
923 Called when beginning the backup of a file.
927 char *fname; /* Full path and filename */
928 char *link; /* Link name if any */
929 struct stat statp; /* System stat() packet for file */
930 int32_t type; /* FT_xx for this file */
931 uint32_t flags; /* Bacula internal flags */
932 bool portable; /* set if data format is portable */
933 char *cmd; /* command */
939 \subsection{endBackupFile(bpContext *ctx)}
940 Called at the end of backing up a file.
942 \subsection{startRestoreFile(bpContext *ctx, const char *cmd)}
943 Called when beginning to restore a file.
947 int32_t stream; /* attribute stream id */
948 int32_t data_stream; /* id of data stream to follow */
949 int32_t type; /* file type FT */
950 int32_t file_index; /* file index */
951 int32_t LinkFI; /* file index to data if hard link */
952 uid_t uid; /* userid */
953 struct stat statp; /* decoded stat packet */
954 const char *attrEx; /* extended attributes if any */
955 const char *ofname; /* output filename */
956 const char *olname; /* output link name */
957 const char *where; /* where */
958 const char *RegexWhere; /* regex where */
959 int replace; /* replace flag */
964 \subsection{endRestoreFile(bpContext *ctx)}
965 Called when done restoring a file.
967 \subsection{pluginIO(bpContext *ctx, struct io\_pkt *io)}
968 Called to do the input (backup) or output (restore) of data from or to a
981 int32_t func; /* Function code */
982 int32_t count; /* read/write count */
983 mode_t mode; /* permissions for created files */
984 int32_t flags; /* open flags (e.g. O_WRONLY ...) */
985 char *buf; /* read/write buffer */
986 int32_t status; /* return status */
987 int32_t io_errno; /* errno code */
995 \subsection{createFile(bpContext *ctx, struct restore\_pkt *rp)}
996 Called to create a file before restoring the data.
1000 struct restore_pkt {
1001 int32_t stream; /* attribute stream id */
1002 int32_t data_stream; /* id of data stream to follow */
1003 int32_t type; /* file type FT */
1004 int32_t file_index; /* file index */
1005 int32_t LinkFI; /* file index to data if hard link */
1006 uid_t uid; /* userid */
1007 struct stat statp; /* decoded stat packet */
1008 const char *attrEx; /* extended attributes if any */
1009 const char *ofname; /* output filename */
1010 const char *olname; /* output link name */
1011 const char *where; /* where */
1012 const char *RegexWhere; /* regex where */
1013 int replace; /* replace flag */
1017 \subsection{setFileAttributes(bpContext *ctx, struct restore\_pkt *rp)}
1020 struct restore_pkt {
1021 int32_t stream; /* attribute stream id */
1022 int32_t data_stream; /* id of data stream to follow */
1023 int32_t type; /* file type FT */
1024 int32_t file_index; /* file index */
1025 int32_t LinkFI; /* file index to data if hard link */
1026 uid_t uid; /* userid */
1027 struct stat statp; /* decoded stat packet */
1028 const char *attrEx; /* extended attributes if any */
1029 const char *ofname; /* output filename */
1030 const char *olname; /* output link name */
1031 const char *where; /* where */
1032 const char *RegexWhere; /* regex where */
1033 int replace; /* replace flag */