1Bareos FD Plugin API 2==================== 3 4To write a Bareos plugin, you create a dynamic shared object program (or 5dll on Win32) with a particular name and two exported entry points, 6place it in the **Plugins Directory**, which is defined in the 7**bareos-fd.conf** file in the **Client** resource, and when the FD 8starts, it will load all the plugins that end with **-fd.so** (or 9**-fd.dll** on Win32) found in that directory. 10 11Normal vs Command vs Options Plugins 12------------------------------------ 13 14In general, there are three ways that plugins are called. The first way, 15is when a particular event is detected in Bareos, it will transfer 16control to each plugin that is loaded in turn informing the plugin of 17the event. This is very similar to how a **RunScript** works, and the 18events are very similar. Once the plugin gets control, it can interact 19with Bareos by getting and setting Bareos variables. In this way, it 20behaves much like a RunScript. Currently very few Bareos variables are 21defined, but they will be implemented as the need arises, and it is very 22extensible. 23 24We plan to have plugins register to receive events that they normally 25would not receive, such as an event for each file examined for backup or 26restore. This feature is not yet implemented. 27 28The second type of plugin, which is more useful and fully implemented in 29the current version is what we call a command plugin. As with all 30plugins, it gets notified of important events as noted above (details 31described below), but in addition, this kind of plugin can accept a 32command line, which is a: 33 34:: 35 36 Plugin = <command-string> 37 38directive that is placed in the Include section of a FileSet and is very 39similar to the “File =” directive. When this Plugin directive is 40encountered by Bareos during backup, it passes the “command” part of the 41Plugin directive only to the plugin that is explicitly named in the 42first field of that command string. This allows that plugin to backup 43any file or files on the system that it wants. It can even create 44“virtual files” in the catalog that contain data to be restored but do 45not necessarily correspond to actual files on the filesystem. 46 47The important features of the command plugin entry points are: 48 49- It is triggered by a “Plugin =” directive in the FileSet 50 51- Only a single plugin is called that is named on the “Plugin =” 52 directive. 53 54- The full command string after the “Plugin =” is passed to the plugin 55 so that it can be told what to backup/restore. 56 57The third type of plugin is the Options Plugin, this kind of plugin is 58useful to implement some custom filter on data. For example, you can 59implement a compression algorithm in a very simple way. Bareos will call 60this plugin for each file that is selected in a FileSet (according to 61Wild/Regex/Exclude/Include rules). As with all plugins, it gets notified 62of important events as noted above (details described below), but in 63addition, this kind of plugin can be placed in a Options group, which is 64a: 65 66:: 67 68 FileSet { 69 Name = TestFS 70 Include { 71 Options { 72 Compression = GZIP1 73 Signature = MD5 74 Wild = "*.txt" 75 Plugin = <command-string> 76 } 77 File = / 78 } 79 } 80 81Loading Plugins 82--------------- 83 84Once the File daemon loads the plugins, it asks the OS for the two entry 85points (loadPlugin and unloadPlugin) then calls the **loadPlugin** entry 86point (see below). 87 88Bareos passes information to the plugin through this call and it gets 89back information that it needs to use the plugin. Later, Bareos will 90call particular functions that are defined by the **loadPlugin** 91interface. 92 93When Bareos is finished with the plugin (when Bareos is going to exit), 94it will call the **unloadPlugin** entry point. 95 96The two entry points are: 97 98:: 99 100 bRC loadPlugin(bInfo *lbinfo, bFuncs *lbfuncs, pInfo **pinfo, pFuncs **pfuncs) 101 102 and 103 104 bRC unloadPlugin() 105 106both these external entry points to the shared object are defined as C 107entry points to avoid name mangling complications with C++. However, the 108shared object can actually be written in any language (preferably C or 109C++) providing that it follows C language calling conventions. 110 111The definitions for **bRC** and the arguments are 112**src/filed/fd-plugins.h** and so this header file needs to be included 113in your plugin. It along with **src/lib/plugins.h** define basically the 114whole plugin interface. Within this header file, it includes the 115following files: 116 117:: 118 119 #include <sys/types.h> 120 #include "config.h" 121 #include "bc_types.h" 122 #include "lib/plugins.h" 123 #include <sys/stat.h> 124 125Aside from the **bc_types.h** and **confit.h** headers, the plugin 126definition uses the minimum code from Bareos. The bc_types.h file is 127required to ensure that the data type definitions in arguments 128correspond to the Bareos core code. 129 130The return codes are defined as: 131 132:: 133 134 typedef enum { 135 bRC_OK = 0, /* OK */ 136 bRC_Stop = 1, /* Stop calling other plugins */ 137 bRC_Error = 2, /* Some kind of error */ 138 bRC_More = 3, /* More files to backup */ 139 bRC_Term = 4, /* Unload me */ 140 bRC_Seen = 5, /* Return code from checkFiles */ 141 bRC_Core = 6, /* Let Bareos core handles this file */ 142 bRC_Skip = 7, /* Skip the proposed file */ 143 } bRC; 144 145At a future point in time, we hope to make the Bareos libbac.a into a 146shared object so that the plugin can use much more of Bareos’s 147infrastructure, but for this first cut, we have tried to minimize the 148dependence on Bareos. 149 150loadPlugin 151---------- 152 153As previously mentioned, the **loadPlugin** entry point in the plugin is 154called immediately after Bareos loads the plugin when the File daemon 155itself is first starting. This entry point is only called once during 156the execution of the File daemon. In calling the plugin, the first two 157arguments are information from Bareos that is passed to the plugin, and 158the last two arguments are information about the plugin that the plugin 159must return to Bareos. The call is: 160 161:: 162 163 bRC loadPlugin(bInfo *lbinfo, bFuncs *lbfuncs, pInfo **pinfo, pFuncs **pfuncs) 164 165and the arguments are: 166 167lbinfo 168 This is information about Bareos in general. Currently, the only 169 value defined in the bInfo structure is the version, which is the 170 Bareos plugin interface version, currently defined as 1. The 171 **size** is set to the byte size of the structure. The exact 172 definition of the bInfo structure as of this writing is: 173 174 :: 175 176 typedef struct s_bareosInfo { 177 uint32_t size; 178 uint32_t version; 179 } bInfo; 180 181lbfuncs 182 The bFuncs structure defines the callback entry points within Bareos 183 that the plugin can use register events, get Bareos values, set 184 Bareos values, and send messages to the Job output or debug output. 185 186 The exact definition as of this writing is: 187 188 :: 189 190 typedef struct s_bareosFuncs { 191 uint32_t size; 192 uint32_t version; 193 bRC (*registerBareosEvents)(bpContext *ctx, ...); 194 bRC (*getBareosValue)(bpContext *ctx, bVariable var, void *value); 195 bRC (*setBareosValue)(bpContext *ctx, bVariable var, void *value); 196 bRC (*JobMessage)(bpContext *ctx, const char *file, int line, 197 int type, utime_t mtime, const char *fmt, ...); 198 bRC (*DebugMessage)(bpContext *ctx, const char *file, int line, 199 int level, const char *fmt, ...); 200 void *(*bareosMalloc)(bpContext *ctx, const char *file, int line, 201 size_t size); 202 void (*bareosFree)(bpContext *ctx, const char *file, int line, void *mem); 203 } bFuncs; 204 205 We will discuss these entry points and how to use them a bit later 206 when describing the plugin code. 207 208pInfo 209 When the loadPlugin entry point is called, the plugin must 210 initialize an information structure about the plugin and return a 211 pointer to this structure to Bareos. 212 213 The exact definition as of this writing is: 214 215 :: 216 217 typedef struct s_pluginInfo { 218 uint32_t size; 219 uint32_t version; 220 const char *plugin_magic; 221 const char *plugin_license; 222 const char *plugin_author; 223 const char *plugin_date; 224 const char *plugin_version; 225 const char *plugin_description; 226 } pInfo; 227 228 Where: 229 230 version 231 is the current Bareos defined plugin interface version, 232 currently set to 1. If the interface version differs from the 233 current version of Bareos, the plugin will not be run (not yet 234 implemented). 235 plugin_magic 236 is a pointer to the text string “\*FDPluginData\*”, a sort of 237 sanity check. If this value is not specified, the plugin will 238 not be run (not yet implemented). 239 plugin_license 240 is a pointer to a text string that describes the plugin license. 241 Bareos will only accept compatible licenses (not yet 242 implemented). 243 plugin_author 244 is a pointer to the text name of the author of the program. This 245 string can be anything but is generally the author’s name. 246 plugin_date 247 is the pointer text string containing the date of the plugin. 248 This string can be anything but is generally some human readable 249 form of the date. 250 plugin_version 251 is a pointer to a text string containing the version of the 252 plugin. The contents are determined by the plugin writer. 253 plugin_description 254 is a pointer to a string describing what the plugin does. The 255 contents are determined by the plugin writer. 256 257 The pInfo structure must be defined in static memory because Bareos 258 does not copy it and may refer to the values at any time while the 259 plugin is loaded. All values must be supplied or the plugin will not 260 run (not yet implemented). All text strings must be either ASCII or 261 UTF-8 strings that are terminated with a zero byte. 262 263pFuncs 264 When the loadPlugin entry point is called, the plugin must 265 initialize an entry point structure about the plugin and return a 266 pointer to this structure to Bareos. This structure contains pointer 267 to each of the entry points that the plugin must provide for Bareos. 268 When Bareos is actually running the plugin, it will call the defined 269 entry points at particular times. All entry points must be defined. 270 271 The pFuncs structure must be defined in static memory because Bareos 272 does not copy it and may refer to the values at any time while the 273 plugin is loaded. 274 275 The exact definition as of this writing is: 276 277 :: 278 279 typedef struct s_pluginFuncs { 280 uint32_t size; 281 uint32_t version; 282 bRC (*newPlugin)(bpContext *ctx); 283 bRC (*freePlugin)(bpContext *ctx); 284 bRC (*getPluginValue)(bpContext *ctx, pVariable var, void *value); 285 bRC (*setPluginValue)(bpContext *ctx, pVariable var, void *value); 286 bRC (*handlePluginEvent)(bpContext *ctx, bEvent *event, void *value); 287 bRC (*startBackupFile)(bpContext *ctx, struct save_pkt *sp); 288 bRC (*endBackupFile)(bpContext *ctx); 289 bRC (*startRestoreFile)(bpContext *ctx, const char *cmd); 290 bRC (*endRestoreFile)(bpContext *ctx); 291 bRC (*pluginIO)(bpContext *ctx, struct io_pkt *io); 292 bRC (*createFile)(bpContext *ctx, struct restore_pkt *rp); 293 bRC (*setFileAttributes)(bpContext *ctx, struct restore_pkt *rp); 294 bRC (*checkFile)(bpContext *ctx, char *fname); 295 } pFuncs; 296 297 The details of the entry points will be presented in separate 298 sections below. 299 300 Where: 301 302 size 303 is the byte size of the structure. 304 version 305 is the plugin interface version currently set to 3. 306 307 Sample code for loadPlugin: 308 309 :: 310 311 bfuncs = lbfuncs; /* set Bareos funct pointers */ 312 binfo = lbinfo; 313 *pinfo = &pluginInfo; /* return pointer to our info */ 314 *pfuncs = &pluginFuncs; /* return pointer to our functions */ 315 316 return bRC_OK; 317 318 where pluginInfo and pluginFuncs are statically defined structures. 319 See bpipe-fd.c for details. 320 321Plugin Entry Points 322------------------- 323 324This section will describe each of the entry points (subroutines) within 325the plugin that the plugin must provide for Bareos, when they are called 326and their arguments. As noted above, pointers to these subroutines are 327passed back to Bareos in the pFuncs structure when Bareos calls the 328loadPlugin() externally defined entry point. 329 330newPlugin(bpContext \*ctx) 331~~~~~~~~~~~~~~~~~~~~~~~~~~ 332 333This is the entry point that Bareos will call when a new “instance” of 334the plugin is created. This typically happens at the beginning of a Job. 335If 10 Jobs are running simultaneously, there will be at least 10 336instances of the plugin. 337 338The bpContext structure will be passed to the plugin, and during this 339call, if the plugin needs to have its private working storage that is 340associated with the particular instance of the plugin, it should create 341it from the heap (malloc the memory) and store a pointer to its private 342working storage in the **pContext** variable. Note: since Bareos is a 343multi-threaded program, you must not keep any variable data in your 344plugin unless it is truly meant to apply globally to the whole plugin. 345In addition, you must be aware that except the first and last call to 346the plugin (loadPlugin and unloadPlugin) all the other calls will be 347made by threads that correspond to a Bareos job. The bpContext that will 348be passed for each thread will remain the same throughout the Job thus 349you can keep your private Job specific data in it (**bContext**). 350 351:: 352 353 typedef struct s_bpContext { 354 void *pContext; /* Plugin private context */ 355 void *bContext; /* Bareos private context */ 356 } bpContext; 357 358This context pointer will be passed as the first argument to all the 359entry points that Bareos calls within the plugin. Needless to say, the 360plugin should not change the bContext variable, which is Bareos’s 361private context pointer for this instance (Job) of this plugin. 362 363freePlugin(bpContext \*ctx) 364~~~~~~~~~~~~~~~~~~~~~~~~~~~ 365 366This entry point is called when the this instance of the plugin is no 367longer needed (the Job is ending), and the plugin should release all 368memory it may have allocated for this particular instance (Job) i.e. the 369pContext. This is not the final termination of the plugin signaled by a 370call to **unloadPlugin**. Any other instances (Job) will continue to 371run, and the entry point **newPlugin** may be called again if other jobs 372start. 373 374getPluginValue(bpContext \*ctx, pVariable var, void \*value) 375~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 376 377Bareos will call this entry point to get a value from the plugin. This 378entry point is currently not called. 379 380setPluginValue(bpContext \*ctx, pVariable var, void \*value) 381~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 382 383Bareos will call this entry point to set a value in the plugin. This 384entry point is currently not called. 385 386handlePluginEvent(bpContext \*ctx, bEvent \*event, void \*value) 387~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 388 389This entry point is called when Bareos encounters certain events 390(discussed below). This is, in fact, the main way that most plugins get 391control when a Job runs and how they know what is happening in the job. 392It can be likened to the **RunScript** feature that calls external 393programs and scripts, and is very similar to the Bareos Python 394interface. When the plugin is called, Bareos passes it the pointer to an 395event structure (bEvent), which currently has one item, the eventType: 396 397:: 398 399 typedef struct s_bEvent { 400 uint32_t eventType; 401 } bEvent; 402 403which defines what event has been triggered, and for each event, Bareos 404will pass a pointer to a value associated with that event. If no value 405is associated with a particular event, Bareos will pass a NULL pointer, 406so the plugin must be careful to always check value pointer prior to 407dereferencing it. 408 409The current list of events are: 410 411:: 412 413 typedef enum { 414 bEventJobStart = 1, 415 bEventJobEnd = 2, 416 bEventStartBackupJob = 3, 417 bEventEndBackupJob = 4, 418 bEventStartRestoreJob = 5, 419 bEventEndRestoreJob = 6, 420 bEventStartVerifyJob = 7, 421 bEventEndVerifyJob = 8, 422 bEventBackupCommand = 9, 423 bEventRestoreCommand = 10, 424 bEventLevel = 11, 425 bEventSince = 12, 426 bEventCancelCommand = 13, /* Executed by another thread */ 427 428 /* Just before bEventVssPrepareSnapshot */ 429 bEventVssBackupAddComponents = 14, 430 431 bEventVssRestoreLoadComponentMetadata = 15, 432 bEventVssRestoreSetComponentsSelected = 16, 433 bEventRestoreObject = 17, 434 bEventEndFileSet = 18, 435 bEventPluginCommand = 19, 436 bEventVssBeforeCloseRestore = 21, 437 438 /* Add drives to VSS snapshot 439 * argument: char[27] drivelist 440 * You need to add them without duplicates, 441 * see fd_common.h add_drive() copy_drives() to get help 442 */ 443 bEventVssPrepareSnapshot = 22, 444 bEventOptionPlugin = 23, 445 bEventHandleBackupFile = 24 /* Used with Options Plugin */ 446 447 } bEventType; 448 449Most of the above are self-explanatory. 450 451bEventJobStart 452 is called whenever a Job starts. The value passed is a pointer to a 453 string that contains: “Jobid=nnn Job=job-name”. Where nnn will be 454 replaced by the JobId and job-name will be replaced by the Job name. 455 The variable is temporary so if you need the values, you must copy 456 them. 457bEventJobEnd 458 is called whenever a Job ends. No value is passed. 459bEventStartBackupJob 460 is called when a Backup Job begins. No value is passed. 461bEventEndBackupJob 462 is called when a Backup Job ends. No value is passed. 463bEventStartRestoreJob 464 is called when a Restore Job starts. No value is passed. 465bEventEndRestoreJob 466 is called when a Restore Job ends. No value is passed. 467bEventStartVerifyJob 468 is called when a Verify Job starts. No value is passed. 469bEventEndVerifyJob 470 is called when a Verify Job ends. No value is passed. 471bEventBackupCommand 472 is called prior to the bEventStartBackupJob and the plugin is passed 473 the command string (everything after the equal sign in “Plugin =” as 474 the value. 475 476 Note, if you intend to backup a file, this is an important first 477 point to write code that copies the command string passed into your 478 pContext area so that you will know that a backup is being performed 479 and you will know the full contents of the “Plugin =” command ( 480 i.e. what to backup and what virtual filename the user wants to call 481 it. 482 483bEventRestoreCommand 484 is called prior to the bEventStartRestoreJob and the plugin is 485 passed the command string (everything after the equal sign in 486 “Plugin =” as the value. 487 488 See the notes above concerning backup and the command string. This 489 is the point at which Bareos passes you the original command string 490 that was specified during the backup, so you will want to save it in 491 your pContext area for later use when Bareos calls the plugin again. 492 493bEventLevel 494 is called when the level is set for a new Job. The value is a 32 bit 495 integer stored in the void*, which represents the Job Level code. 496bEventSince 497 is called when the since time is set for a new Job. The value is a 498 time_t time at which the last job was run. 499bEventCancelCommand 500 is called whenever the currently running Job is cancelled. Be warned 501 that this event is sent by a different thread. 502bEventVssBackupAddComponents 503 bEventPluginCommand 504 is called for each PluginCommand present in the current FileSet. The 505 event will be sent only on plugin specifed in the command. The 506 argument is the PluginCommand (not valid after the call). 507bEventHandleBackupFile 508 is called for each file of a FileSet when using a Options Plugin. If 509 the plugin returns CF_OK, it will be used for the backup, if it 510 returns CF_SKIP, the file will be skipped. Anything else will backup 511 the file with Bareos core functions. 512 513During each of the above calls, the plugin receives either no specific 514value or only one value, which in some cases may not be sufficient. 515However, knowing the context of the event, the plugin can call back to 516the Bareos entry points it was passed during the **loadPlugin** call and 517get to a number of Bareos variables. (at the current time few Bareos 518variables are implemented, but it easily extended at a future time and 519as needs require). 520 521startBackupFile(bpContext \*ctx, struct save_pkt \*sp) 522~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 523 524This entry point is called only if your plugin is a command plugin, and 525it is called when Bareos encounters the “Plugin =” directive in the 526Include section of the FileSet. Called when beginning the backup of a 527file. Here Bareos provides you with a pointer to the **save_pkt** 528structure and you must fill in this packet with the “attribute” data of 529the file. 530 531:: 532 533 struct save_pkt { 534 int32_t pkt_size; /* size of this packet */ 535 char *fname; /* Full path and filename */ 536 char *link; /* Link name if any */ 537 struct stat statp; /* System stat() packet for file */ 538 int32_t type; /* FT_xx for this file */ 539 uint32_t flags; /* Bareos internal flags */ 540 bool portable; /* set if data format is portable */ 541 char *cmd; /* command */ 542 uint32_t delta_seq; /* Delta sequence number */ 543 char *object_name; /* Object name to create */ 544 char *object; /* restore object data to save */ 545 int32_t object_len; /* restore object length */ 546 int32_t index; /* restore object index */ 547 int32_t pkt_end; /* end packet sentinel */ 548 }; 549 550The second argument is a pointer to the **save_pkt** structure for the 551file to be backed up. The plugin is responsible for filling in all the 552fields of the **save_pkt**. If you are backing up a real file, then 553generally, the statp structure can be filled in by doing a **stat** 554system call on the file. 555 556If you are backing up a database or something that is more complex, you 557might want to create a virtual file. That is a file that does not 558actually exist on the filesystem, but represents say an object that you 559are backing up. In that case, you need to ensure that the **fname** 560string that you pass back is unique so that it does not conflict with a 561real file on the system, and you need to artifically create values in 562the statp packet. 563 564Example programs such as **bpipe-fd.c** show how to set these fields. 565You must take care not to store pointers the stack in the pointer fields 566such as fname and link, because when you return from your function, your 567stack entries will be destroyed. The solution in that case is to 568malloc() and return the pointer to it. In order to not have memory 569leaks, you should store a pointer to all memory allocated in your 570pContext structure so that in subsequent calls or at termination, you 571can release it back to the system. 572 573Once the backup has begun, Bareos will call your plugin at the 574**pluginIO** entry point to “read” the data to be backed up. Please see 575the **bpipe-fd.c** plugin for how to do I/O. 576 577Example of filling in the save_pkt as used in bpipe-fd.c: 578 579:: 580 581 struct plugin_ctx *p_ctx = (struct plugin_ctx *)ctx->pContext; 582 time_t now = time(NULL); 583 sp->fname = p_ctx->fname; 584 sp->statp.st_mode = 0700 | S_IFREG; 585 sp->statp.st_ctime = now; 586 sp->statp.st_mtime = now; 587 sp->statp.st_atime = now; 588 sp->statp.st_size = -1; 589 sp->statp.st_blksize = 4096; 590 sp->statp.st_blocks = 1; 591 p_ctx->backup = true; 592 return bRC_OK; 593 594Note: the filename to be created has already been created from the 595command string previously sent to the plugin and is in the plugin 596context (p_ctx->fname) and is a malloc()ed string. This example creates 597a regular file (S_IFREG), with various fields being created. 598 599In general, the sequence of commands issued from Bareos to the plugin to 600do a backup while processing the “Plugin =” directive are: 601 6021. generate a bEventBackupCommand event to the specified plugin and pass 603 it the command string. 604 6052. make a startPluginBackup call to the plugin, which fills in the data 606 needed in save_pkt to save as the file attributes and to put on the 607 Volume and in the catalog. 608 6093. call Bareos’s internal save_file() subroutine to save the specified 610 file. The plugin will then be called at pluginIO() to “open” the 611 file, and then to read the file data. Note, if you are dealing with a 612 virtual file, the “open” operation is something the plugin does 613 internally and it doesn’t necessarily mean opening a file on the 614 filesystem. For example in the case of the bpipe-fd.c program, it 615 initiates a pipe to the requested program. Finally when the plugin 616 signals to Bareos that all the data was read, Bareos will call the 617 plugin with the “close” pluginIO() function. 618 619endBackupFile(bpContext \*ctx) 620~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 621 622Called at the end of backing up a file for a command plugin. If the 623plugin’s work is done, it should return bRC_OK. If the plugin wishes to 624create another file and back it up, then it must return bRC_More (not 625yet implemented). This is probably a good time to release any malloc()ed 626memory you used to pass back filenames. 627 628startRestoreFile(bpContext \*ctx, const char \*cmd) 629~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 630 631Called when the first record is read from the Volume that was previously 632written by the command plugin. 633 634createFile(bpContext \*ctx, struct restore_pkt \*rp) 635~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 636 637Called for a command plugin to create a file during a Restore job before 638restoring the data. This entry point is called before any I/O is done on 639the file. After this call, Bareos will call pluginIO() to open the file 640for write. 641 642The data in the restore_pkt is passed to the plugin and is based on the 643data that was originally given by the plugin during the backup and the 644current user restore settings (e.g. where, RegexWhere, replace). This 645allows the plugin to first create a file (if necessary) so that the data 646can be transmitted to it. The next call to the plugin will be a pluginIO 647command with a request to open the file write-only. 648 649This call must return one of the following values: 650 651:: 652 653 enum { 654 CF_SKIP = 1, /* skip file (not newer or something) */ 655 CF_ERROR, /* error creating file */ 656 CF_EXTRACT, /* file created, data to extract */ 657 CF_CREATED, /* file created, no data to extract */ 658 CF_CORE /* let bareos core handles the file creation */ 659 }; 660 661in the restore_pkt value **create_status**. For a normal file, unless 662there is an error, you must return **CF_EXTRACT**. 663 664:: 665 666 struct restore_pkt { 667 int32_t pkt_size; /* size of this packet */ 668 int32_t stream; /* attribute stream id */ 669 int32_t data_stream; /* id of data stream to follow */ 670 int32_t type; /* file type FT */ 671 int32_t file_index; /* file index */ 672 int32_t LinkFI; /* file index to data if hard link */ 673 uid_t uid; /* userid */ 674 struct stat statp; /* decoded stat packet */ 675 const char *attrEx; /* extended attributes if any */ 676 const char *ofname; /* output filename */ 677 const char *olname; /* output link name */ 678 const char *where; /* where */ 679 const char *RegexWhere; /* regex where */ 680 int replace; /* replace flag */ 681 int create_status; /* status from createFile() */ 682 int32_t pkt_end; /* end packet sentinel */ 683 684 }; 685 686Typical code to create a regular file would be the following: 687 688:: 689 690 struct plugin_ctx *p_ctx = (struct plugin_ctx *)ctx->pContext; 691 time_t now = time(NULL); 692 sp->fname = p_ctx->fname; /* set the full path/filename I want to create */ 693 sp->type = FT_REG; 694 sp->statp.st_mode = 0700 | S_IFREG; 695 sp->statp.st_ctime = now; 696 sp->statp.st_mtime = now; 697 sp->statp.st_atime = now; 698 sp->statp.st_size = -1; 699 sp->statp.st_blksize = 4096; 700 sp->statp.st_blocks = 1; 701 return bRC_OK; 702 703This will create a virtual file. If you are creating a file that 704actually exists, you will most likely want to fill the statp packet 705using the stat() system call. 706 707Creating a directory is similar, but requires a few extra steps: 708 709:: 710 711 struct plugin_ctx *p_ctx = (struct plugin_ctx *)ctx->pContext; 712 time_t now = time(NULL); 713 sp->fname = p_ctx->fname; /* set the full path I want to create */ 714 sp->link = xxx; where xxx is p_ctx->fname with a trailing forward slash 715 sp->type = FT_DIREND 716 sp->statp.st_mode = 0700 | S_IFDIR; 717 sp->statp.st_ctime = now; 718 sp->statp.st_mtime = now; 719 sp->statp.st_atime = now; 720 sp->statp.st_size = -1; 721 sp->statp.st_blksize = 4096; 722 sp->statp.st_blocks = 1; 723 return bRC_OK; 724 725The link field must be set with the full cononical path name, which 726always ends with a forward slash. If you do not terminate it with a 727forward slash, you will surely have problems later. 728 729As with the example that creates a file, if you are backing up a real 730directory, you will want to do an stat() on the directory. 731 732Note, if you want the directory permissions and times to be correctly 733restored, you must create the directory **after** all the file 734directories have been sent to Bareos. That allows the restore process to 735restore all the files in a directory using default directory options, 736then at the end, restore the directory permissions. If you do it the 737other way around, each time you restore a file, the OS will modify the 738time values for the directory entry. 739 740setFileAttributes(bpContext \*ctx, struct restore_pkt \*rp) 741~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 742 743This is call not yet implemented. Called for a command plugin. 744 745See the definition of **restre_pkt** in the above section. 746 747endRestoreFile(bpContext \*ctx) 748~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 749 750Called when a command plugin is done restoring a file. 751 752pluginIO(bpContext \*ctx, struct io_pkt \*io) 753~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 754 755Called to do the input (backup) or output (restore) of data from or to a 756file for a command plugin. These routines simulate the Unix read(), 757write(), open(), close(), and lseek() I/O calls, and the arguments are 758passed in the packet and the return values are also placed in the 759packet. In addition for Win32 systems the plugin must return two 760additional values (described below). 761 762:: 763 764 enum { 765 IO_OPEN = 1, 766 IO_READ = 2, 767 IO_WRITE = 3, 768 IO_CLOSE = 4, 769 IO_SEEK = 5 770 }; 771 772 struct io_pkt { 773 int32_t pkt_size; /* Size of this packet */ 774 int32_t func; /* Function code */ 775 int32_t count; /* read/write count */ 776 mode_t mode; /* permissions for created files */ 777 int32_t flags; /* Open flags */ 778 char *buf; /* read/write buffer */ 779 const char *fname; /* open filename */ 780 int32_t status; /* return status */ 781 int32_t io_errno; /* errno code */ 782 int32_t lerror; /* Win32 error code */ 783 int32_t whence; /* lseek argument */ 784 boffset_t offset; /* lseek argument */ 785 bool win32; /* Win32 GetLastError returned */ 786 int32_t pkt_end; /* end packet sentinel */ 787 }; 788 789The particular Unix function being simulated is indicated by the 790**func**, which will have one of the IO_OPEN, IO_READ, … codes listed 791above. The status code that would be returned from a Unix call is 792returned in **status** for IO_OPEN, IO_CLOSE, IO_READ, and IO_WRITE. The 793return value for IO_SEEK is returned in **offset** which in general is a 79464 bit value. 795 796When there is an error on Unix systems, you must always set io_error, 797and on a Win32 system, you must always set win32, and the returned value 798from the OS call GetLastError() in lerror. 799 800For all except IO_SEEK, **status** is the return result. In general it 801is a positive integer unless there is an error in which case it is -1. 802 803The following describes each call and what you get and what you should 804return: 805 806IO_OPEN 807 You will be passed fname, mode, and flags. You must set on return: 808 status, and if there is a Unix error io_errno must be set to the 809 errno value, and if there is a Win32 error win32 and lerror. 810IO_READ 811 You will be passed: count, and buf (buffer of size count). You must 812 set on return: status to the number of bytes read into the buffer 813 (buf) or -1 on an error, and if there is a Unix error io_errno must 814 be set to the errno value, and if there is a Win32 error, win32 and 815 lerror must be set. 816IO_WRITE 817 You will be passed: count, and buf (buffer of size count). You must 818 set on return: status to the number of bytes written from the buffer 819 (buf) or -1 on an error, and if there is a Unix error io_errno must 820 be set to the errno value, and if there is a Win32 error, win32 and 821 lerror must be set. 822IO_CLOSE 823 Nothing will be passed to you. On return you must set status to 0 on 824 success and -1 on failure. If there is a Unix error io_errno must be 825 set to the errno value, and if there is a Win32 error, win32 and 826 lerror must be set. 827IO_LSEEK 828 You will be passed: offset, and whence. offset is a 64 bit value and 829 is the position to seek to relative to whence. whence is one of the 830 following SEEK_SET, SEEK_CUR, or SEEK_END indicating to either to 831 seek to an absolute possition, relative to the current position or 832 relative to the end of the file. You must pass back in offset the 833 absolute location to which you seeked. If there is an error, offset 834 should be set to -1. If there is a Unix error io_errno must be set 835 to the errno value, and if there is a Win32 error, win32 and lerror 836 must be set. 837 838 Note: Bareos will call IO_SEEK only when writing a sparse file. 839 840bool checkFile(bpContext \*ctx, char \*fname) 841~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 842 843If this entry point is set, Bareos will call it after backing up all 844file data during an Accurate backup. It will be passed the full filename 845for each file that Bareos is proposing to mark as deleted. Only files 846previously backed up but not backed up in the current session will be 847marked to be deleted. If you return **false**, the file will be be 848marked deleted. If you return **true** the file will not be marked 849deleted. This permits a plugin to ensure that previously saved virtual 850files or files controlled by your plugin that have not change (not 851backed up in the current job) are not marked to be deleted. This entry 852point will only be called during Accurate Incrmental and Differential 853backup jobs. 854 855Bareos Plugin Entrypoints 856------------------------- 857 858When Bareos calls one of your plugin entrypoints, you can call back to 859the entrypoints in Bareos that were supplied during the xxx plugin call 860to get or set information within Bareos. 861 862bRC registerBareosEvents(bpContext \*ctx, …) 863~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 864 865This Bareos entrypoint will allow you to register to receive events that 866are not autmatically passed to your plugin by default. This entrypoint 867currently is unimplemented. 868 869bRC getBareosValue(bpContext \*ctx, bVariable var, void \*value) 870~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 871 872Calling this entrypoint, you can obtain specific values that are 873available in Bareos. The following Variables can be referenced: 874 875- bVarJobId returns an int 876 877- bVarFDName returns a char \* 878 879- bVarLevel returns an int 880 881- bVarClient returns a char \* 882 883- bVarJobName returns a char \* 884 885- bVarJobStatus returns an int 886 887- bVarSinceTime returns an int (time_t) 888 889- bVarAccurate returns an int 890 891bRC setBareosValue(bpContext \*ctx, bVariable var, void \*value) 892~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 893 894Calling this entrypoint allows you to set particular values in Bareos. 895The only variable that can currently be set is **bVarFileSeen** and the 896value passed is a char \* that points to the full filename for a file 897that you are indicating has been seen and hence is not deleted. 898 899bRC JobMessage(bpContext \*ctx, const char \*file, int line, int type, utime_t mtime, const char \*fmt, …) 900~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 901 902This call permits you to put a message in the Job Report. 903 904bRC DebugMessage(bpContext \*ctx, const char \*file, int line, int level, const char \*fmt, …) 905~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 906 907This call permits you to print a debug message. 908 909void bareosMalloc(bpContext \*ctx, const char \*file, int line, size_t size) 910~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 911 912This call permits you to obtain memory from Bareos’s memory allocator. 913 914void bareosFree(bpContext \*ctx, const char \*file, int line, void \*mem) 915~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 916 917This call permits you to free memory obtained from Bareos’s memory 918allocator. 919 920Building Bareos Plugins 921----------------------- 922 923There is currently one sample program **example-plugin-fd.c** and one 924working plugin **bpipe-fd.c** that can be found in the Bareos 925**src/plugins/fd** directory. Both are built with the following: 926 927:: 928 929 cd <bareos-source> 930 ./configure <your-options> 931 make 932 ... 933 cd src/plugins/fd 934 make 935 make test 936 937After building Bareos and changing into the src/plugins/fd directory, 938the **make** command will build the **bpipe-fd.so** plugin, which is a 939very useful and working program. 940 941The **make test** command will build the **example-plugin-fd.so** plugin 942and a binary named **main**, which is build from the source code located 943in **src/filed/fd_plugins.c**. 944 945If you execute **./main**, it will load and run the example-plugin-fd 946plugin simulating a small number of the calling sequences that Bareos 947uses in calling a real plugin. This allows you to do initial testing of 948your plugin prior to trying it with Bareos. 949 950You can get a good idea of how to write your own plugin by first 951studying the example-plugin-fd, and actually running it. Then it can 952also be instructive to read the bpipe-fd.c code as it is a real plugin, 953which is still rather simple and small. 954 955When actually writing your own plugin, you may use the 956example-plugin-fd.c code as a template for your code. 957