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 The return codes are defined as:
685 bRC_Stop = 1, /* Stop calling other plugins */
686 bRC_Error = 2, /* Some kind of error */
687 bRC_More = 3, /* More files to backup */
692 At a future point in time, we hope to make the Bacula libbac.a into a
693 shared object so that the plugin can use much more of Bacula's
694 infrastructure, but for this first cut, we have tried to minimize the
695 dependence on Bacula.
698 As previously mentioned, the {\bf loadPlugin} entry point in the plugin
699 is called immediately after Bacula loads the plugin. In calling the
700 plugin, the first two arguments are information from Bacula that
701 is passed to the plugin, and the last two arguments are information
702 about the plugin that is returned to Bacula. The call is:
705 bRC loadPlugin(bInfo *lbinfo, bFuncs *lbfuncs, pInfo **pinfo, pFuncs **pfuncs)
708 and the arguments are:
712 This is information about Bacula in general. Currently, the only value
713 defined in the bInfo structure is version, which is the Bacula plugin
714 interface version, currently defined as 1.
715 The exact definition as of this writing is:
718 typedef struct s_baculaInfo {
725 The bFuncs structure defines the callback entry points within Bacula
726 that the plugin can use register events, get Bacula values, set
727 Bacula values, and send messages to the Job output.
729 The exact definition as of this writing is:
732 ypedef struct s_baculaFuncs {
735 bRC (*registerBaculaEvents)(bpContext *ctx, ...);
736 bRC (*getBaculaValue)(bpContext *ctx, bVariable var, void *value);
737 bRC (*setBaculaValue)(bpContext *ctx, bVariable var, void *value);
738 bRC (*JobMessage)(bpContext *ctx, const char *file, int line,
739 int type, time_t mtime, const char *fmt, ...);
740 bRC (*DebugMessage)(bpContext *ctx, const char *file, int line,
741 int level, const char *fmt, ...);
745 We will discuss these entry points and how to use them a bit later when
746 describing the plugin code.
749 When the loadPlugin entry point is called, the plugin must initialize
750 an information structure about the plugin and return a pointer to
751 this structure to Bacula.
753 The exact definition as of this writing is:
756 typedef struct s_pluginInfo {
759 const char *plugin_magic;
760 const char *plugin_license;
761 const char *plugin_author;
762 const char *plugin_date;
763 const char *plugin_version;
764 const char *plugin_description;
770 \item [version] is the current plugin interface version, currently
772 \item [plugin\_magic] is a pointer to the string "*FDPluginData*", a
773 sort of sanity check.
774 \item [plugin\_license] is a pointer to a string that describes the
776 \item [plugin\_author] is a pointer to the name of the author of the program.
777 \item [plugin\_date] is the pointer string containing the date of the plugin.
778 \item [plugin\_version] is a pointer to a string containing the version of
780 \item [plugin\_description] is a pointer to a string describing what the
784 The pInfo structure must be defined in static memory because Bacula does not
785 copy it and may refer to the values at any time while the plugin is
789 When the loadPlugin entry point is called, the plugin must initialize
790 an entry point structure about the plugin and return a pointer to
791 this structure to Bacula. This structure contains pointer to each
792 of the entry points that the plugin must provide for Bacula. When
793 Bacula is actually running the plugin, it will call the defined
794 entry points at particular times. All entry points must be defined.
796 The pFuncs structure must be defined in static memory because Bacula does not
797 copy it and may refer to the values at any time while the plugin is
801 The exact definition as of this writing is:
804 typedef struct s_pluginFuncs {
807 bRC (*newPlugin)(bpContext *ctx);
808 bRC (*freePlugin)(bpContext *ctx);
809 bRC (*getPluginValue)(bpContext *ctx, pVariable var, void *value);
810 bRC (*setPluginValue)(bpContext *ctx, pVariable var, void *value);
811 bRC (*handlePluginEvent)(bpContext *ctx, bEvent *event, void *value);
812 bRC (*startBackupFile)(bpContext *ctx, struct save_pkt *sp);
813 bRC (*endBackupFile)(bpContext *ctx);
814 bRC (*startRestoreFile)(bpContext *ctx, const char *cmd);
815 bRC (*endRestoreFile)(bpContext *ctx);
816 bRC (*pluginIO)(bpContext *ctx, struct io_pkt *io);
817 bRC (*createFile)(bpContext *ctx, struct restore_pkt *rp);
818 bRC (*setFileAttributes)(bpContext *ctx, struct restore_pkt *rp);
822 The details of the entry points will be presented in
823 separate sections below.
827 \item [size] is the size of the structure.
828 \item [version] is the plugin interface version.
833 \section{Plugin Entry Points}
834 This section will describe each of the entry points that
835 the plugin must provide for Bacula, when they are called
838 \subsection{newPlugin(bpContext *ctx)}
839 This is the entry point that Bacula will call
840 when a new instance of the plugin is created. This typically
841 happens at the beginning of a Job. If 10 Jobs are running
842 simultaneously, there will be at least 10 instances of the
845 The bpContext structure will be passed to the plugin, and
846 during this call, if the plugin needs to have its private
847 working storage that is associated with the particular
848 instance of the plugin, it should create it from the heap
849 (malloc the memory) and store a pointer to
850 its private working storage in the {\bf pContext} variable.
853 typedef struct s_bpContext {
854 void *pContext; /* Plugin private context */
855 void *bContext; /* Bacula private context */
860 This context pointer will be passed as the first argument to all
861 the entry points that Bacula calls within the plugin. Needless
862 to say, the plugin should not change the bContext variable, which
863 is Bacula's private context pointer for this instance of this
866 \subsection{freePlugin(bpContext *ctx)}
867 This entry point is called when the
868 this instance of the plugin is no longer needed (the Job is
869 ending), and the plugin should release all memory it may
870 have allocated for the pContext.
872 \subsection{getPluginValue(bpContext *ctx, pVariable var, void *value)}
873 Bacula will call this entry point to get
874 a value from the plugin. This entry point is currently not called.
876 \subsection{setPluginValue(bpContext *ctx, pVariable var, void *value)}
877 Bacula will call this entry point to set
878 a value in the plugin. This entry point is currently not called.
880 \subsection{handlePluginEvent(bpContext *ctx, bEvent *event, void *value)}
881 This entry point is called when Bacula
882 encounters certain events (discussed below). Bacula passes the pointer to an event
883 structure (bEvent), which currently has one item, the eventType:
886 typedef struct s_bEvent {
891 which defines what event has been triggered, and for each event,
892 Bacula will pass a pointer to a value associated with that event.
893 If no value is associated with a particular event, Bacula will
894 pass a NULL pointer, so you must always check for it.
896 The current list of events are:
902 bEventStartBackupJob = 3,
903 bEventEndBackupJob = 4,
904 bEventStartRestoreJob = 5,
905 bEventEndRestoreJob = 6,
906 bEventStartVerifyJob = 7,
907 bEventEndVerifyJob = 8,
908 bEventBackupCommand = 9,
909 bEventRestoreCommand = 10,
916 Most of which are pretty explanatory.
919 \item [bEventJobStart] is called whenever a Job starts. The value
920 passed is a pointer to a string that contains: "Jobid=nnn
921 Job=job-name". Where nnn will be replaced by the JobId and job-name
922 will be replaced by the Job name. The variable is temporary so if you
923 need the values, you must copy them.
924 \item [bEventJobEnd] is called whenever a Job ends. No value is passed.
925 \item [bEventStartBackupJob] is called when a Backup Job begins. No value
927 \item [bEventEndBackupJob] is called when a Backup Job ends. No value is
929 \item [bEventStartRestoreJob] is called when a Restore Job starts. No value
931 \item [bEventEndRestoreJob] is called when a Restore Job ends. No value is
933 \item [bEventStartVerifyJob] is called when a Verify Job starts. No value
935 \item [bEventEndVerifyJob] is called when a Verify Job ends. No value
937 \item [bEventBackupCommand] is called prior to the bEventStartBackupJob and
938 the plugin is passed the command string (everything after the equal sign
939 in "Plugin =" as the value.
940 \item [bEventRestoreCommand] is called prior to the bEventStartRestoreJob and
941 the plugin is passed the command string (everything after the equal sign
942 in "Plugin =" as the value.
943 \item [bEventLevel] is called when the level is set for a new Job. The value
944 is a 32 bit integer stored in the void*, which represents the Job Level code.
945 \item [bEventSince] is called when the since time is set for a new Job. The
946 value is a time\_t time at which the last job was run.
949 \subsection{startBackupFile(bpContext *ctx, struct save\_pkt *sp)}
950 Called when beginning the backup of a file.
954 char *fname; /* Full path and filename */
955 char *link; /* Link name if any */
956 struct stat statp; /* System stat() packet for file */
957 int32_t type; /* FT_xx for this file */
958 uint32_t flags; /* Bacula internal flags */
959 bool portable; /* set if data format is portable */
960 char *cmd; /* command */
964 The second argument is a pointer to the {\bf save\_pkt} structure for the file
965 to be backed up. The plugin is responsible for filling in all the fields
966 of the {\bf save\_pkt}. The values in the {\bf save\_pkt} are used to create a virtual file
967 entry in the Bacula catalog database. The full path and filename should be
968 unique on the system to avoid conflicts with real files. Example programs such
969 as {\bf bpipe.c} show how to set these fields.
971 Once the backup has begun, Bacula will call your plugin at the {\bf pluginIO}
972 entry point to "read" the data to be backed up. Please see the {\bf bpipe.c}
973 plugin for how to do I/O.
975 \subsection{endBackupFile(bpContext *ctx)}
976 Called at the end of backing up a file. If the plugin's work
977 is done, it should return bRC\_OK. If the plugin wishes to create another
978 file and back it up, then it must return bRC\_More (not yet implemented).
980 \subsection{startRestoreFile(bpContext *ctx, const char *cmd)}
984 \subsection{endRestoreFile(bpContext *ctx)}
985 Called when done restoring a file.
987 \subsection{pluginIO(bpContext *ctx, struct io\_pkt *io)}
988 Called to do the input (backup) or output (restore) of data from or to a
1001 int32_t func; /* Function code */
1002 int32_t count; /* read/write count */
1003 mode_t mode; /* permissions for created files */
1004 int32_t flags; /* open flags (e.g. O_WRONLY ...) */
1005 char *buf; /* read/write buffer */
1006 int32_t status; /* return status */
1007 int32_t io_errno; /* errno code */
1014 \subsection{createFile(bpContext *ctx, struct restore\_pkt *rp)}
1015 Called to create a file before restoring the data. The data in the
1016 restore\_pkt is passed to the plugin and is based on the data that was
1017 originally given by the plugin during the backup and the current user
1018 restore settings (e.g. where, RegexWhere, replace). This allows the
1019 plugin to first create a file (if necessary) so that the data can
1020 be transmitted to it. The next call to the plugin will be a
1021 pluginIO command with a request to open the file write-only.
1025 struct restore_pkt {
1026 int32_t stream; /* attribute stream id */
1027 int32_t data_stream; /* id of data stream to follow */
1028 int32_t type; /* file type FT */
1029 int32_t file_index; /* file index */
1030 int32_t LinkFI; /* file index to data if hard link */
1031 uid_t uid; /* userid */
1032 struct stat statp; /* decoded stat packet */
1033 const char *attrEx; /* extended attributes if any */
1034 const char *ofname; /* output filename */
1035 const char *olname; /* output link name */
1036 const char *where; /* where */
1037 const char *RegexWhere; /* regex where */
1038 int replace; /* replace flag */
1042 \subsection{setFileAttributes(bpContext *ctx, struct restore\_pkt *rp)}
1043 This is call not yet implemented.
1046 struct restore_pkt {
1047 int32_t stream; /* attribute stream id */
1048 int32_t data_stream; /* id of data stream to follow */
1049 int32_t type; /* file type FT */
1050 int32_t file_index; /* file index */
1051 int32_t LinkFI; /* file index to data if hard link */
1052 uid_t uid; /* userid */
1053 struct stat statp; /* decoded stat packet */
1054 const char *attrEx; /* extended attributes if any */
1055 const char *ofname; /* output filename */
1056 const char *olname; /* output link name */
1057 const char *where; /* where */
1058 const char *RegexWhere; /* regex where */
1059 int replace; /* replace flag */