[bacula/docs] / docs / manuals / en / concepts / newfeatures.tex

%%
%%

\chapter{New Features}
\label{NewFeaturesChapter}
\index[general]{New Features}

This chapter presents the new features added to the development 2.5.x
versions to be released as Bacula version 3.0.0 near the end of 2008.

\section{Accurate}
\index[general]{Accurate Backup}
As with most other backup programs, Bacula decides what files to backup 
for Incremental and Differental backup by comparing the change (st\_ctime)
and modification (st\_mtime) times of the file to the time the last backup completed.
If one of those two times is later than the last backup time, then the file
will be backed up.  This does not, however, permit tracking what files have
been deleted and will miss any file with an old time that may have been
restored or moved on the client filesystem.

If the {\bf Accurate = \lt{}yes|no\gt{}} directive is enabled (default no) in the
Job resource, the job will be run as an Accurate Job. For a {\bf Full}
backup, there is no difference, but for {\bf Differential} and {\bf Incremental}
backups, the Director will send a list of all previous files backed up, and the 
File daemon will use that list to determine if any new files have been added or
or moved and if any files have been deleted. This allows Bacula to make an accurate
backup of your system to that point in time so that if you do a restore, it
will restore your system exactly.  One note of caution about using Accurate backup is that
it requires more resources (CPU and memory) on both the Director and
the Client machines to create the list of previous files backed up, to send that
list to the File daemon, for the File daemon to keep the list (possibly very big)
in memory, and for the File daemon to do comparisons between every file in the 
FileSet and the list.


\section{Copy Jobs}
\index[general]{Copy Jobs}
A new {\bf Copy} job type has been implemented. It is essentially
identical to the existing Migration feature with the exception that
the Job that is copied is left unchanged.  This essentially creates
two identical copies of the same backup.  The Copy Job runs without
using the File daemon by copying the data from the old backup Volume to
a different Volume in a different Pool. See the Migration documentation
for additional details.

\section{Virtual Backup (Vbackup)}
\index[general]{Virtual Backup}
\index[general]{Vbackup}

Bacula's virtual backup feature is often called Synthetic Backup or
Consolidation in other backup products.  It permits you to consolidate
the previous Full backup plus the most recent Differential backup and any
subsequent Incremental backups into a new Full backup. This is accomplished
without contacting the client by reading the previous backup data and 
writing it to a volume in a different pool.  

In some respects the Vbackup feature works similar to a Migration job, in
that Bacula normally reads the data from the pool specified in the 
Job resource, and writes it to the {\bf Next Pool} specified in the 
Job resource.  The input Storage resource and the Output Storage resource
must be different.

The Vbackup is enabled on a Job by Job in the Job resource by specifying
a level of {\bf VirtualFull}.

A typical Job resource definition might look like the following:

\begin{verbatim}
Job {
  Name = "MyBackup"
  Type = Backup
  Client=localhost-fd
  FileSet = "Full Set"
  Storage = File
  Messages = Standard
  Pool = Default
  SpoolData = yes
}

# Default pool definition
Pool {
  Name = Default
  Pool Type = Backup
  Recycle = yes            # Automatically recycle Volumes
  AutoPrune = yes          # Prune expired volumes
  Volume Retention = 365d  # one year
  NextPool = Full
  Storage = File
}

Pool {
  Name = Full
  Pool Type = Backup
  Recycle = yes            # Automatically recycle Volumes
  AutoPrune = yes          # Prune expired volumes
  Volume Retention = 365d  # one year
  Storage = DiskChanger
}

# Definition of file storage device
Storage {
  Name = File
  Address = localhost
  Password = "xxx"
  Device = FileStorage
  Media Type = File
  Maximum Concurrent Jobs = 5
}

# Definition of DDS Virtual tape disk storage device
Storage {
  Name = DiskChanger
  Address = localhost  # N.B. Use a fully qualified name here
  Password = "yyy"
  Device = DiskChanger
  Media Type = DiskChangerMedia
  Maximum Concurrent Jobs = 4
  Autochanger = yes
}
\end{verbatim}

Then in bconsole or via a Run schedule, you would run the job as:

\begin{verbatim}
run job=MyBackup level=Full
run job=MyBackup level=Incremental
run job=MyBackup level=Differential
run job=MyBackup level=Incremental
run job=MyBackup level=Incremental
\end{verbatim}

So providing there were changes between each of those jobs, you would end up
with a Full backup, a Differential, which includes the first Incremental
backup, then two Incremental backups.  All the above jobs would be written to
the {\bf Default} pool.

To consolidate those backups into a new Full backup, you would run the
following:

\begin{verbatim}
run job=MyBackup level=VirtualFull
\end{verbatim}

And it would produce a new Full backup without using the client, and the output
would be written to the {\bf Full} Pool which uses the Diskchanger Storage.

\section{Duplicate Job Control}
\index[general]{Duplicate Jobs}
The new version of Bacula provides four new directives that
give additional control over what Bacula does if duplicate jobs 
are started.  A duplicate job in the sense we use it here means
a second or subsequent job with the same name starts.  This
happens most frequently when the first job runs longer than expected because no 
tapes are available.

The four directives each take as an argument a {\bf yes} or {\bf no} value and
are specified in the Job resource.

They are:

\begin{description}
\item [Allow Duplicate Jobs = \lt{}yes|no\gt{}]
  If this directive is enabled duplicate jobs will be run.  If
  the directive is set to {\bf no} (default) then only one job of a given name
  may run at one time, and the action that Bacula takes to ensure only
  one job runs is determined by the other directives (see below).

\item [Allow Higher Duplicates = \lt{}yes|no\gt{}]
  If this directive is set to {\bf yes} (default) the job with a higher
  priority (lower priority number) will be permitted to run.  If the
  priorities of the two jobs are the same, the outcome is determined by
  other directives (see below).

\item [Cancel Queued Duplicates = \lt{}yes|no\gt{}]
  If this directive is set to {\bf yes} (default) any job that is
  already queued to run but not yet running will be canceled.

\item [Cancel Running Duplicates = \lt{}yes|no\gt{}]
  If this directive is set to {\bf yes} any job that is already running
  will be canceled.  The default is {\bf no}.
\end{description}

\section{TLS Authentication}
\index[general]{TLS Authentication}
In Bacula version 2.5.x and later, in addition to the normal Bacula
CRAM-MD5 authentication that is used to authenticate each Bacula
connection, you can specify that you want TLS Authentication as well,
which will provide more secure authentication.

This new feature uses Bacula's existing TLS code (normally used for
communications encryption) to do authentication.  To use it, you must
specify all the TLS directives normally used to enable communications
encryption (TLS Enable, TLS Verify Peer, TLS Certificate, ...) and
a new directive:

\begin{verbatim}
TLS Authenticate = yes
\end{verbatim}

in the main daemon configuration resource (Director for the Director,
Client for the File daemon, and Storage for the Storage daemon).

When {\bf TLS Authenticate} is enabled, after doing the CRAM-MD5
authentication, Bacula will do the normal TLS authentication, then TLS 
encryption will be turned off.

If you want to encrypt communications data, do not turn on {\bf TLS
Authenticate}.

\section{bextract non-portable Win32 data}
\index[general]{bextract handles Win32 non-portable data}
{\bf bextract} has been enhanced to be able to restore
non-portable Win32 data to any OS.  Previous versions were 
unable to restore non-portable Win32 data to machines that
did not have the Win32 BackupRead and BackupWrite API calls.

\section{State File updated at Job Termination}
\index[general]{State File}
In previous versions of Bacula, the state file, which provides a
summary of previous jobs run in the {\bf status} command output was
updated only when Bacula terminated, thus if the daemon crashed, the
state file might not contain all the run data.  This version of
the Bacula daemons updates the state file on each job termination.

\section{MaxFullInterval}
\index[general]{MaxFullInterval}
The new Job resource directive {\bf Max Full Interval = \lt{}time-interval\gt{}}
can be used to specify the maximum time interval between {\bf Full} backup
jobs. When a job starts, if the time since the last Full backup is
greater than the specified interval, and the job would normally be an
{\bf Incremental} or {\bf Differential}, it will be automatically
upgraded to a {\bf Full} backup.

\section{MaxDiffInterval}
\index[general]{MaxDiffInterval}
The new Job resource directive {\bf Max Diff Interval = \lt{}time-interval\gt{}}
can be used to specify the maximum time interval between {\bf Differential} backup
jobs. When a job starts, if the time since the last Differential backup is
greater than the specified interval, and the job would normally be an
{\bf Incremental}, it will be automatically
upgraded to a {\bf Differential} backup.

\section{No Dump Flag}
\index[general]{MaxDiffInterval}
On FreeBSD systems, each file has a {\bf no dump flag} that can be set
by the user, and when it is set it is an indication to backup programs
to not backup that particular file.  This version of Bacula contains a
new Options directive within a FileSet resource, which instructs Bacula to
obey this flag.  The new directive is:

\begin{verbatim}
  Honor No Dump Flag = yes|no
\end{verbatim}

The default value is {\bf no}.


\section{Ignore Dir}
\index[general]{IgnoreDir}
The {\bf Ignore Dir = \lt{}filename\gt{}} is a new directive that can be added to the Include
section of the FileSet resource.  If the specified
filename is found on the Client in any directory to be backed up, 
the whole directory will be ignored (not backed up).
For example:

\begin{verbatim}
  # List of files to be backed up
  FileSet {
    Name = "MyFileSet"
    Include {
      Options {
        signature = MD5
      }
      File = /home
      IgnoreDir = .excludeme
    }
  }
\end{verbatim}

But in /home, there may be hundreds of directories of users and some
people want to indicate that they don't want to have certain
directories backed up. For example, with the above FileSet, if
the user or sysadmin creates a file named {\bf .excludeme} in 
specific directories, such as

\begin{verbatim}
   /home/user/www/cache/.excludeme
   /home/user/temp/.excludeme
\end{verbatim}

then Bacula will not backup the two directories named:

\begin{verbatim}
   /home/user/www/cache
   /home/user/temp
\end{verbatim}




\section{Bacula Plugins}
\index[general]{Plugin}
Support for shared object plugins has been implemented in the Linux
(and Unix) File daemon. The API will be documented separately in
the Developer's Guide or in a new document.  For the moment, there is
a single plugin named {\bf bpipe} that allows an external program to
get control to backup and restore a file.

Plugins are also planned (partially implemented) in the Director and the
Storage daemon.  The code is also implemented to work on Win32 machines, 
but it has not yet been tested.

\subsection{Plugin Directory}
Each daemon (DIR, FD, SD) has a new {\bf Plugin Directory} directive that may
be added to the daemon definition resource. The directory takes a quoted 
string argument, which is the name of the directory in which the daemon can
find the Bacula plugins. If this directive is not specified, Bacula will not
load any plugins. Since each plugin has a distinctive name, all the daemons
can share the same plugin directory. 



\subsection{Plugin Options}
The {\bf Plugin Options} directive takes a quoted string
arguement (after the equal sign) and may be specified in the
Job resource.  The options specified will be passed to the plugin
when it is run.  The value defined in the Job resource can be modified
by the user when he runs a Job via the {\bf bconsole} command line 
prompts.

Note: this directive may be specified, but it is not yet passed to
the plugin (i.e. not fully implemented).

\subsection{Plugin Options ACL}
The {\bf Plugin Options ACL} directive may be specified in the
Director's Console resource. It functions as all the other ACL commands
do by permitting users running restricted consoles to specify a 
{\bf Plugin Options} that overrides the one specified in the Job
definition. Without this directive restricted consoles may not modify
the Plugin Options.

\subsection{Plugin}
The {\bf Plugin} directive is specified in the Include section of
a FileSet resource where you put your {\bf File = xxx} directives.
For example:

\begin{verbatim}
  FileSet {
    Name = "MyFileSet"
    Include {
      Options {
        signature = MD5
      }
      File = /home
      Plugin = "bpipe:..."
    }
  }
\end{verbatim}

In the above example, when the File daemon is processing the directives
in the Include section, it will first backup all the files in {\bf /home}
then it will load the plugin named {\bf bpipe} (actually bpipe-dir.so) from
the Plugin Directory.  The syntax and semantics of the Plugin directive
require the first part of the string up to the colon (:) to be the name
of the plugin. Everything after the first colon is ignored by the File daemon but
is passed to the plugin. Thus the plugin writer may define the meaning of the
rest of the string as he wishes.

Please see the next section for information about the {\bf bpipe} Bacula
plugin.

\section{The bpipe Plugin}
The {\bf bpipe} plugin is provided in the directory src/plugins/fd/bpipe-fd.c of
the Bacula source distribution. When the plugin is compiled and linking into
the resulting dynamic shared object (DSO), it will have the name {\bf bpipe-fd.so}.

The purpose of the plugin is to provide an interface to any system program for
backup and restore. As specified above the {\bf bpipe} plugin is specified in
the Include section of your Job's FileSet resource.  The full syntax of the
plugin directive as interpreted by the {\bf bpipe} plugin (each plugin is free
to specify the sytax as it wishes) is:

\begin{verbatim}
  Plugin = "<field1>:<field2>:<field3>:<field4>"
\end{verbatim}

where
\begin{description}
\item {\bf field1} is the name of the plugin with the trailing {\bf -fd.so}
stripped off, so in this case, we would put {\bf bpipe} in this field.

\item {\bf field2} specifies the namespace, which for {\bf bpipe} is the
pseudo path and filename under which the backup will be saved. This pseudo
path and filename will be seen by the user in the restore file tree.
For example, if the value is {\bf /MYSQL/regress.sql}, the data
backed up by the plugin will be put under that "pseudo" path and filename.
You must be careful to choose a naming convention that is unique to avoid
a conflict with a path and filename that actually exists on your system.

\item {\bf field3} for the {\bf bpipe} plugin 
specifies the "reader" program that is called by the plugin during
backup to read the data. {\bf bpipe} will call this program by doing a
{\bf popen} on it.

\item {\bf field4} for the {\bf bpipe} plugin
specifies the "writer" program that is called by the plugin during
restore to write the data back to the filesystem.  
\end{description}

Putting it all together, the full plugin directive line might look
like the following:

\begin{verbatim}
Plugin = "bpipe:/MYSQL/regress.sql:mysqldump -f 
          --opt --databases bacula:mysql"
\end{verbatim}

The directive has been split into two lines, but within the {\bf bacula-dir.conf} file
would be written on a single line.

This causes the File daemon to call the {\bf bpipe} plugin, which will write
its data into the "pseudo" file {\bf /MYSQL/regress.sql} by calling the 
program {\bf mysqldump -f --opt --database bacula} to read the data during
backup. The mysqldump command outputs all the data for the database named
{\bf bacula}, which will be read by the plugin and stored in the backup.
During restore, the data that was backed up will be sent to the program
specified in the last field, which in this case is {\bf mysql}.  When
{\bf mysql} is called, it will read the data sent to it by the plugn
then write it back to the same database from which it came ({\bf bacula}
in this case).

The {\bf bpipe} plugin is a generic pipe program, that simply transmits 
the data from a specified program to Bacula for backup, and then from Bacula to 
a specified program for restore.

By using different command lines to {\bf bpipe},
you can backup any kind of data (ASCII or binary) depending
on the program called.

\section{libdbi framework}
As a general guideline, Bacula has support for a few catalog database drivers
coded natively by the Bacula team.  With the libdbi implementation, which is a
Bacula driver that uses libdbi to access the catalog, we have an open field to
use many different kinds database engines following the needs of users.

The according to libdbi (http://libdbi.sourceforge.net/) project: libdbi
implements a database-independent abstraction layer in C, similar to the
DBI/DBD layer in Perl. Writing one generic set of code, programmers can
leverage the power of multiple databases and multiple simultaneous database
connections by using this framework.

Currently the libdbi driver in Bacula project only supports the same drivers
natively coded in Bacula.  However the libdbi project has support for many
others database engines. You can view the list at
http://libdbi-drivers.sourceforge.net/. In the future all those drivers can be
supported by Bacula, however, they must be tested properly by the Bacula team.

Some of benefits of using libdbi are:
\begin{itemize}
\item The possibility to use proprietary databases engines in which your
  proprietary licenses prevent the Bacula team from developing the driver.
 \item The possibility to use the drivers written for the libdbi project.
 \item The possibility to use other database engines without recompiling Bacula
   to use them.  Just change one line in bacula-dir.conf
 \item Abstract Database access, this is, unique point to code and profiling
   catalog database access.
 \end{itemize}
 
 The following drivers have been tested:
 \begin{itemize}
 \item PostgreSQL, with and without batch insert
 \item Mysql, with and without batch insert
 \item SQLite
 \item SQLite3
 \end{itemize}

 In the future, we will test and approve to use others databases engines
 (proprietary or not) like DB2, Oracle, Microsoft SQL.

 To compile Bacula to support libdbi we need to configure the code with the
 --with-dbi and --with-dbi-driver=[database] ./configure options, where
 [database] is the database engine to be used with Bacula (of course we can
 change the driver in file bacula-dir.conf, see below).  We must configure the
 access port of the database engine with the option --with-db-port, because the
 libdbi framework doesn't know the default access port of each database.

The next phase is checking (or configuring) the bacula-dir.conf, example:
\begin{verbatim}
Catalog {
  Name = MyCatalog
  dbdriver = dbi:mysql; dbaddress = 127.0.0.1; dbport = 3306
  dbname = regress; user = regress; password = ""
}
\end{verbatim}

The parameter {\bf dbdriver} indicates that we will use the driver dbi with a
mysql database.  Currently the drivers supported by Bacula are: postgresql,
mysql, sqlite, sqlite3; these are the names that may be added to string "dbi:".

The following limitations apply when Bacula is set to use the libdbi framework:
 - Not tested on the Win32 platform
 - A little performance is lost if comparing with native database driver. 
   The reason is bound with the database driver provided by libdbi and the 
   simple fact that one more layer of code was added.

It is important to remember, when compiling Bacula with libdbi, the
following packages are needed:
 \begin{itemize}
  \item libdbi version 1.0.0, http://libdbi.sourceforge.net/
  \item libdbi-drivers 1.0.0, http://libdbi-drivers.sourceforge.net/
 \end{itemize}
 
 You can download them and compile them on your system or install the packages
 from your OS distribution.


\section{Display Autochanger Content}
\index[general]{StatusSlots}

The {\bf status slots storage=\lt{}storage-name\gt{}} command displays autochanger content.

\footnotesize
\begin{verbatim}
 Slot |  Volume Name  |  Status  |  Media Type       |   Pool     |  Loaded |
------+---------------+----------+-------------------+------------+---------|
    1 |         00001 |   Append |  DiskChangerMedia |    Default |    0    |
    2 |         00002 |   Append |  DiskChangerMedia |    Default |    0    |
    3*|         00003 |   Append |  DiskChangerMedia |    Scratch |    0    |
    4 |               |          |                   |            |    0    |
\end{verbatim}
\normalsize

If you an asterisk ({\bf *}) appears after the slot number, you must run an
{\bf update slots} command to synchronize autochanger content with your
catalog.

\section{Miscellaneous}
\index[general]{Misc New Features}
\begin{description}
\item [Virtual Tape Emulation]

We now have a Virtual Tape emulator that allows us to run though 99.9\% of
the tape code but actually reading and writing to a disk file. Used with the
\textbf{disk-changer} script, you can now emulate an autochanger with 10 drives
and 700 slots. This feature is most useful in testing.  It is enabled
by using {\bf Device Type = vtape} in the Storage daemon's Device
directive. This feature is only implemented on Linux machines.

\item [Bat Enhancements]
Bat (the Bacula Administration Tool) GUI program has been significantly
enhanced and stabilized. In particular, there are new table based status 
commands; it can now be easily localized using Qt4 Linguist.

The Bat communications protocol has been significantly enhanced to improve
GUI handling.

\item [RunScript Enhancements]
The {\bf RunScript} resource has been enhanced to permit multiple
commands per RunScript.  Simply specify multiple {\bf Command} directives
in your RunScript.

\begin{verbatim}
Job {
  Name = aJob
  RunScript {
    Command = "/bin/echo test"
    Command = "/bin/echo an other test"
    Command = "/bin/echo 3 commands in the same runscript"
    RunsWhen = Before
  }
 ...
}
\end{verbatim}

A new Client RunScript {\bf RunsWhen} keyword of {\bf AfterVSS} has been implemented, which
runs the command after the Volume Shadow Copy has been made.

Console commands can be specified within a RunScript by using:
{\bf Console = \lt{}command\gt{}}, however, this command has not been 
carefully tested and debugged and is known to easily crash the Director.
We would appreciate feedback.  Due to the recursive nature of this command, we
may remove it before the final release.

\item [Status Enhancements]
The bconsole {\bf status dir} output has been enhanced to indicate
Storage daemon job spooling and despooling activity.

\item [Connect Timeout]
The default connect timeout to the File
daemon has been set to 3 minutes. Previously it was 30 minutes.

\item [ftruncate for NFS Volumes]
If you write to a Volume mounted by NFS (say on a local file server),
in previous Bacula versions, when the Volume was recycled, it was not
properly truncated because NFS does not implement ftruncate (file 
truncate). This is now corrected in the new version because we have
written code (actually a kind user) that deletes and recreates the Volume,
thus accomplishing the same thing as a truncate.

\item [Support for Ubuntu]
The new version of Bacula now recognizes the Ubuntu (and Kubuntu)
version of Linux, and thus now provides correct autostart routines.
Since Ubuntu officially supports Bacula, you can also obtain any
recent release of Bacula from the Ubuntu repositories.

\item[Recycling enhancements]
The new \textbf{RecyclePool} directive defines to which pool the Volume will
be placed (moved) when it is recycled. Without this directive, a Volume will
remain in the same pool when it is recycled. With this directive, it can be
moved automatically to any existing pool during a recycle. This directive is
probably most useful when defined in the Scratch pool, so that volumes will
be recycled back into the Scratch pool.

\item [FD Version]
The File daemon to Director protocol now includes a version 
number, which will help us in future versions automatically determine
if a File daemon is not compatible.

\item [Max Run Sched Time]
The time specifies the maximum allowed time that a job may run, counted from
when the job was scheduled. This can be useful to prevent jobs from running
during working hours. We can see it like \texttt{Max Start Delay + Max Run
  Time}.

\item [Max Wait Time]
Previous \textbf{MaxWaitTime} directives aren't working as expected, instead
of checking the maximum allowed time that a job may block for a resource,
those directives worked like \textbf{MaxRunTime}. Some users are reporting to use
\textbf{Incr/Diff/Full Max Wait Time} to control the maximum run time of their job
depending on the level. Now, they have to use \textbf{Incr/Diff/Full Max Run Time}.
\textbf{Incr/Diff/Full Max Wait Time} directives are now deprecated.

\item [Incremental|Differential Max Wait Time = \lt{}time\gt{}] 
Theses directives have been deprecated in favor of \texttt{Incremental|Differential
Max Run Time}.

\item [Max Run Time directives]
Using \textbf{Full/Diff/Incr Max Run Time}, it's now possible to specify the
maximum allowed time that a job can run depending on the level.

\addcontentsline{lof}{figure}{Job time control directives}
\includegraphics{\idir different_time.eps}

\item [Statistics Enhancements]
If you (or your boss) want to have statistics on your backups, you could use
a few SQL queries on the Job table to report how many:
\begin{itemize}
\item jobs have run
\item jobs have been successful
\item files have been backed up
\item ...
\end{itemize}

However, these statistics are accurate only if your job retention is greater than
your statistics period. Ie, if jobs are purged from the catalog, you won't be
able to use them.

Now, you can use the \textbf{update stats [days=num]} console command to fill the
JobStat table with new Job records.

The \textbf{Statistics Retention = \lt{}time\gt{}} director directive defines
the length of time that Bacula will keep statistics job records in the Catalog
database after the Job End time. (In \texttt{JobStat} table) When this time
period expires, and if user runs \texttt{prune stats} command, Bacula will
prune (remove) Job records that are older than the specified period.

These statistics records aren't used for restore purpose, but mainly for
capacity planning, billings, etc.

You can use the following Job resource in your nightly \textbf{BackupCatalog}
job to maintain statistics.
\begin{verbatim}
Job {
  Name = BackupCatalog
  ...
  RunScript {
    Console = "update stats days=3"
    Console = "prune stats yes"
    RunsWhen = After
    RunsOnClient = no
  }
}
\end{verbatim}

\item [Spooling Enhancements]
A new job directive permits to specify the spool size per job. This is used
in advanced job tunning. {\bf SpoolSize={\it bytes}}

\end{description}

\section{Building Bacula Plugins}
There is currently one sample program {\bf example-plugin-fd.c} and
one working plugin {\bf bpipe-fd.c} that can be found in the Bacula
{\bf src/plugins/fd} directory.  Both are built with the following:

\begin{verbatim}
 cd <bacula-source>
 ./configure <your-options>
 make
 ...
 cd src/plugins/fd
 make
 make test
\end{verbatim}

After building Bacula and changing into the src/plugins/fd directory,
the {\bf make} command will build the {\bf bpipe-fd.so} plugin, which 
is a very useful and working program.

The {\bf make test} command will build the {\bf example-plugin-fd.so}
plugin and a binary named {\bf main}, which is build from the source
code located in {\bf src/filed/fd\_plugins.c}. 

If you execute {\bf ./main}, it will load and run the example-plugin-fd
plugin simulating a small number of the calling sequences that Bacula uses
in calling a real plugin.  This allows you to do initial testing of 
your plugin prior to trying it with Bacula.

You can get a good idea of how to write your own plugin by first 
studying the example-plugin-fd, and actually running it.  Then
it can also be instructive to read the bpipe-fd.c code as it is 
a real plugin, which is still rather simple and small.

When actually writing your own plugin, you may use the example-plugin-fd.c
code as a template for your code.


%%
%%

\chapter{Bacula FD Plugin API}
To write a Bacula plugin, you create a dynamic shared object
program (or dll on Win32) with a particular name and two 
exported entry points, place it in the {\bf Plugins Directory}, which is defined in the
{\bf bacula-fd.conf} file in the {\bf Client} resource, and when the FD
starts, it will load all the plugins that end with {\bf -fd.so} (or {\bf -fd.dll}
on Win32) found in that directory.

Once the File daemon loads the plugins, it asks the OS for the
two entry points (loadPlugin and unloadPlugin) then calls the
{\bf loadPlugin} entry point (see below).

Bacula passes information to the plugin through this call and it gets
back information that it needs to use the plugin.  Later, Bacula
 will call particular functions that are defined by the
{\bf loadPlugin} interface.  

When Bacula is finished with the plugin 
(when Bacula is going to exit), it will call the {\bf unloadPlugin}
entry point.

The two entry points are:

\begin{verbatim}
bRC loadPlugin(bInfo *lbinfo, bFuncs *lbfuncs, pInfo **pinfo, pFuncs **pfuncs)

and

bRC unloadPlugin()
\end{verbatim}

both these external entry points to the shared object are defined as C entry points
to avoid name mangling complications with C++.  However, the shared object
can actually be written in any language (preferrably C or C++) providing that it
follows C language calling conventions.

The definitions for {\bf bRC} and the arguments are {\bf
src/filed/fd-plugins.h} and so this header file needs to be included in
your plugin.  It along with {\bf src/lib/plugins.h} define basically the whole
plugin interface.  Within this header file, it includes the following
files:

\begin{verbatim}
#include <sys/types.h>
#include "config.h"
#include "bc_types.h"
#include "lib/plugins.h"
#include <sys/stat.h>
\end{verbatim}

Aside from the {\bf bc\_types.h} and {\bf confit.h} headers, the plugin definition uses the
minimum code from Bacula.  The bc\_types.h file is required to ensure that
the data type defintions in arguments correspond to the Bacula core code.

The return codes are defined as:
\begin{verbatim}
typedef enum {
  bRC_OK    = 0,                         /* OK */
  bRC_Stop  = 1,                         /* Stop calling other plugins */
  bRC_Error = 2,                         /* Some kind of error */
  bRC_More  = 3,                         /* More files to backup */
} bRC;
\end{verbatim}


At a future point in time, we hope to make the Bacula libbac.a into a
shared object so that the plugin can use much more of Bacula's
infrastructure, but for this first cut, we have tried to minimize the
dependence on Bacula.

\section{loadPlugin}
As previously mentioned, the {\bf loadPlugin} entry point in the plugin
is called immediately after Bacula loads the plugin when the File daemon
itself is first starting.  This entry point is only called once during the
execution of the File daemon.  In calling the
plugin, the first two arguments are information from Bacula that
is passed to the plugin, and the last two arguments are information
about the plugin that the plugin must return to Bacula.  The call is:

\begin{verbatim}
bRC loadPlugin(bInfo *lbinfo, bFuncs *lbfuncs, pInfo **pinfo, pFuncs **pfuncs)
\end{verbatim}

and the arguments are:

\begin{description}
\item [lbinfo]
This is information about Bacula in general. Currently, the only value
defined in the bInfo structure is the version, which is the Bacula plugin 
interface version, currently defined as 1.  The {\bf size} is set to the
byte size of the structure. The exact definition of the bInfo structure
as of this writing is: 

\begin{verbatim}
typedef struct s_baculaInfo {
   uint32_t size;
   uint32_t version;
} bInfo;
\end{verbatim}

\item [lbfuncs]
The bFuncs structure defines the callback entry points within Bacula
that the plugin can use register events, get Bacula values, set
Bacula values, and send messages to the Job output or debug output.

The exact definition as of this writing is:
\begin{verbatim}
typedef struct s_baculaFuncs {
   uint32_t size;
   uint32_t version;
   bRC (*registerBaculaEvents)(bpContext *ctx, ...);
   bRC (*getBaculaValue)(bpContext *ctx, bVariable var, void *value);
   bRC (*setBaculaValue)(bpContext *ctx, bVariable var, void *value);
   bRC (*JobMessage)(bpContext *ctx, const char *file, int line,
       int type, time_t mtime, const char *fmt, ...);
   bRC (*DebugMessage)(bpContext *ctx, const char *file, int line,
       int level, const char *fmt, ...);
} bFuncs;
\end{verbatim}

We will discuss these entry points and how to use them a bit later when
describing the plugin code.


\item [pInfo]
When the loadPlugin entry point is called, the plugin must initialize
an information structure about the plugin and return a pointer to
this structure to Bacula.

The exact definition as of this writing is:

\begin{verbatim}
typedef struct s_pluginInfo {
   uint32_t size;
   uint32_t version;
   const char *plugin_magic;
   const char *plugin_license;
   const char *plugin_author;
   const char *plugin_date;
   const char *plugin_version;
   const char *plugin_description;
} pInfo;
\end{verbatim}

Where:
 \begin{description}
 \item [version] is the current Bacula defined plugin interface version, currently
   set to 1. If the interface version differs from the current version of 
   Bacula, the plugin will not be run (not yet implemented).
 \item [plugin\_magic] is a pointer to the text string "*FDPluginData*", a
   sort of sanity check.  If this value is not specified, the plugin
   will not be run (not yet implemented).
 \item [plugin\_license] is a pointer to a text string that describes the
   plugin license. Bacula will only accept compatible licenses (not yet
   implemented).
 \item [plugin\_author] is a pointer to the text name of the author of the program.
   This string can be anything but is generally the author's name.
 \item [plugin\_date] is the pointer text string containing the date of the plugin.
   This string can be anything but is generally some human readable form of 
   the date.
 \item [plugin\_version] is a pointer to a text string containing the version of
   the plugin.  The contents are determined by the plugin writer.
 \item [plugin\_description] is a pointer to a string describing what the
   plugin does. The contents are determined by the plugin writer.
 \end{description}

The pInfo structure must be defined in static memory because Bacula does not
copy it and may refer to the values at any time while the plugin is
loaded. All values must be supplied or the plugin will not run (not yet
implemented).  All text strings must be either ASCII or UTF-8 strings that
are terminated with a zero byte.

\item [pFuncs]
When the loadPlugin entry point is called, the plugin must initialize
an entry point structure about the plugin and return a pointer to
this structure to Bacula. This structure contains pointer to each
of the entry points that the plugin must provide for Bacula. When
Bacula is actually running the plugin, it will call the defined
entry points at particular times.  All entry points must be defined.

The pFuncs structure must be defined in static memory because Bacula does not
copy it and may refer to the values at any time while the plugin is
loaded.

The exact definition as of this writing is:

\begin{verbatim}
typedef struct s_pluginFuncs {
   uint32_t size;
   uint32_t version;
   bRC (*newPlugin)(bpContext *ctx);
   bRC (*freePlugin)(bpContext *ctx);
   bRC (*getPluginValue)(bpContext *ctx, pVariable var, void *value);
   bRC (*setPluginValue)(bpContext *ctx, pVariable var, void *value);
   bRC (*handlePluginEvent)(bpContext *ctx, bEvent *event, void *value);
   bRC (*startBackupFile)(bpContext *ctx, struct save_pkt *sp);
   bRC (*endBackupFile)(bpContext *ctx);
   bRC (*startRestoreFile)(bpContext *ctx, const char *cmd);
   bRC (*endRestoreFile)(bpContext *ctx);
   bRC (*pluginIO)(bpContext *ctx, struct io_pkt *io);
   bRC (*createFile)(bpContext *ctx, struct restore_pkt *rp);
   bRC (*setFileAttributes)(bpContext *ctx, struct restore_pkt *rp);
} pFuncs;
\end{verbatim}

The details of the entry points will be presented in
separate sections below. 

Where:
 \begin{description}
 \item [size] is the byte size of the structure.
 \item [version] is the plugin interface version currently set to 1.
 \end{description}

Sample code for loadPlugin:
\begin{verbatim}
  bfuncs = lbfuncs;                  /* set Bacula funct pointers */
  binfo  = lbinfo;
  *pinfo  = &pluginInfo;             /* return pointer to our info */
  *pfuncs = &pluginFuncs;            /* return pointer to our functions */

   return bRC_OK;
\end{verbatim}

where pluginInfo and pluginFuncs are statically defined structures. 
See bpipe-fd.c for details.



\end{description}

\section{Plugin Entry Points}
This section will describe each of the entry points (subroutines) within
the plugin that the plugin must provide for Bacula, when they are called
and their arguments. As noted above, pointers to these subroutines are
passed back to Bacula in the pFuncs structure when Bacula calls the 
loadPlugin() externally defined entry point.

\subsection{newPlugin(bpContext *ctx)}
  This is the entry point that Bacula will call
  when a new "instance" of the plugin is created. This typically
  happens at the beginning of a Job.  If 10 Jobs are running
  simultaneously, there will be at least 10 instances of the
  plugin.

  The bpContext structure will be passed to the plugin, and
  during this call, if the plugin needs to have its private
  working storage that is associated with the particular
  instance of the plugin, it should create it from the heap
  (malloc the memory) and store a pointer to
  its private working storage in the {\bf pContext} variable.
  Note: since Bacula is a multi-threaded program, you must not
  keep any variable data in your plugin unless it is truely meant
  to apply globally to the whole plugin.  In addition, you must
  be aware that except the first and last call to the plugin
  (loadPlugin and unloadPlugin) all the other calls will be 
  made by threads that correspond to a Bacula job.  The 
  bpContext that will be passed for each thread will remain the
  same throughout the Job thus you can keep your privat Job specific
  data in it ({\bf bContext}).

\begin{verbatim}
typedef struct s_bpContext {
  void *pContext;   /* Plugin private context */
  void *bContext;   /* Bacula private context */
} bpContext;

\end{verbatim}
   
  This context pointer will be passed as the first argument to all
  the entry points that Bacula calls within the plugin.  Needless
  to say, the plugin should not change the bContext variable, which
  is Bacula's private context pointer for this instance (Job) of this
  plugin.

\subsection{freePlugin(bpContext *ctx)}
This entry point is called when the
this instance of the plugin is no longer needed (the Job is
ending), and the plugin should release all memory it may
have allocated for this particular instance (Job) i.e. the pContext.  
This is not the final termination
of the plugin signaled by a call to {\bf unloadPlugin}. 
Any other instances (Job) will
continue to run, and the entry point {\bf newPlugin} may be called
again if other jobs start.

\subsection{getPluginValue(bpContext *ctx, pVariable var, void *value)} 
Bacula will call this entry point to get
a value from the plugin.  This entry point is currently not called.

\subsection{setPluginValue(bpContext *ctx, pVariable var, void *value)}
Bacula will call this entry point to set
a value in the plugin.  This entry point is currently not called.
 
\subsection{handlePluginEvent(bpContext *ctx, bEvent *event, void *value)}
This entry point is called when Bacula
encounters certain events (discussed below). This is, in fact, the 
main way that most plugins get control when a Job runs and how
they know what is happening in the job. It can be likened to the
{\bf RunScript} feature that calls external programs and scripts,
and is very similar to the Bacula Python interface.
When the plugin is called, Bacula passes it the pointer to an event
structure (bEvent), which currently has one item, the eventType:

\begin{verbatim}
typedef struct s_bEvent {
   uint32_t eventType;
} bEvent;
\end{verbatim}

  which defines what event has been triggered, and for each event,
  Bacula will pass a pointer to a value associated with that event.
  If no value is associated with a particular event, Bacula will 
  pass a NULL pointer, so the plugin must be careful to always check
  value pointer prior to dereferencing it.
  
  The current list of events are:

\begin{verbatim}
typedef enum {
  bEventJobStart        = 1,
  bEventJobEnd          = 2,
  bEventStartBackupJob  = 3,
  bEventEndBackupJob    = 4,
  bEventStartRestoreJob = 5,
  bEventEndRestoreJob   = 6,
  bEventStartVerifyJob  = 7,
  bEventEndVerifyJob    = 8,
  bEventBackupCommand   = 9,
  bEventRestoreCommand  = 10,
  bEventLevel           = 11,
  bEventSince           = 12,
} bEventType;

\end{verbatim}
 
Most of the above are self-explanatory.

\begin{description}
 \item [bEventJobStart] is called whenever a Job starts. The value
   passed is a pointer to a string that contains: "Jobid=nnn 
   Job=job-name". Where nnn will be replaced by the JobId and job-name
   will be replaced by the Job name. The variable is temporary so if you
   need the values, you must copy them.

 \item [bEventJobEnd] is called whenever a Job ends. No value is passed.

 \item [bEventStartBackupJob] is called when a Backup Job begins. No value
   is passed.

 \item [bEventEndBackupJob] is called when a Backup Job ends. No value is 
   passed.

 \item [bEventStartRestoreJob] is called when a Restore Job starts. No value
   is passed.

 \item [bEventEndRestoreJob] is called when a Restore Job ends. No value is
   passed.

 \item [bEventStartVerifyJob] is called when a Verify Job starts. No value
   is passed.

 \item [bEventEndVerifyJob] is called when a Verify Job ends. No value
   is passed.

 \item [bEventBackupCommand] is called prior to the bEventStartBackupJob and
   the plugin is passed the command string (everything after the equal sign
   in "Plugin =" as the value.

   Note, if you intend to backup a file, this is an important first point to
   write code that copies the command string passed into your pContext area
   so that you will know that a backup is being performed and you will know
   the full contents of the "Plugin =" command (i.e. what to backup and
   what virtual filename the user wants to call it.

 \item [bEventRestoreCommand] is called prior to the bEventStartRestoreJob and
   the plugin is passed the command string (everything after the equal sign
   in "Plugin =" as the value.

   See the notes above concerning backup and the command string. This is the
   point at which Bacula passes you the original command string that was
   specified during the backup, so you will want to save it in your pContext
   area for later use when Bacula calls the plugin again.

 \item [bEventLevel] is called when the level is set for a new Job. The value
   is a 32 bit integer stored in the void*, which represents the Job Level code.

 \item [bEventSince] is called when the since time is set for a new Job. The 
   value is a time\_t time at which the last job was run.
\end{description}

During each of the above calls, the plugin receives either no specific value or
only one value, which in some cases may not be sufficient.  However, knowing the
context of the event, the plugin can call back to the Bacula entry points it
was passed during the {\bf loadPlugin} call and get to a number of Bacula variables.
(at the current time few Bacula variables are implemented, but it easily extended
at a future time and as needs require).

\subsection{startBackupFile(bpContext *ctx, struct save\_pkt *sp)}
Called when beginning the backup of a file. Here Bacula provides you
with a pointer to the {\bf save\_pkt} structure and you must fill in 
this packet with the "attribute" data of the file.

\begin{verbatim}
 struct save_pkt {
  char *fname;                        /* Full path and filename */
  char *link;                         /* Link name if any */
  struct stat statp;                  /* System stat() packet for file */
  int32_t type;                       /* FT_xx for this file */
  uint32_t flags;                     /* Bacula internal flags */
  bool portable;                      /* set if data format is portable */
  char *cmd;                          /* command */
};
\end{verbatim}

The second argument is a pointer to the {\bf save\_pkt} structure for the file
to be backed up.  The plugin is responsible for filling in all the fields 
of the {\bf save\_pkt}. If you are backing up
a real file, then generally, the statp structure can be filled in by doing
a {\bf stat} system call on the file.  

If you are backing up a database or
something that is more complex, you might want to create a virtual file.
That is a file that does not actually exist on the filesystem, but represents 
say an object that you are backing up.  In that case, you need to ensure
that the {\bf fname} string that you pass back is unique so that it
does not conflict with a real file on the system, and you need to 
artifically create values in the statp packet.

Example programs such as {\bf bpipe-fd.c} show how to set these fields.
You must take care not to store pointers the stack in the pointer fields such
as fname and link, because when you return from your function, your stack entries
will be destroyed. The solution in that case is to malloc() and return the pointer
to it. In order to not have memory leaks, you should store a pointer to all memory
allocated in your pContext structure so that in subsequent calls or at termination,
you can release it back to the system.

Once the backup has begun, Bacula will call your plugin at the {\bf pluginIO}
entry point to "read" the data to be backed up.  Please see the {\bf bpipe-fd.c}
plugin for how to do I/O.

Example of filling in the save\_pkt as used in bpipe-fd.c:

\begin{verbatim}
   struct plugin_ctx *p_ctx = (struct plugin_ctx *)ctx->pContext;
   time_t now = time(NULL);
   sp->fname = p_ctx->fname;
   sp->statp.st_mode = 0700 | S_IFREG;
   sp->statp.st_ctime = now;
   sp->statp.st_mtime = now;
   sp->statp.st_atime = now;
   sp->statp.st_size = -1;
   sp->statp.st_blksize = 4096;
   sp->statp.st_blocks = 1;
   p_ctx->backup = true;
   return bRC_OK; 
\end{verbatim}

Note: the filename to be created has already been created from the 
command string previously sent to the plugin and is in the plugin 
context (p\_ctx->fname) and is a malloc()ed string.  This example
creates a regular file (S\_IFREG), with various fields being created.

In general, the sequence of commands issued from Bacula to the plugin
to do a backup while processing the "Plugin = " directive are:

\begin{enumerate}
 \item generate a bEventBackupCommand event to the specified plugin
       and pass it the command string.
 \item make a startPluginBackup call to the plugin, which
       fills in the data needed in save\_pkt to save as the file
       attributes and to put on the Volume and in the catalog.
 \item call Bacula's internal save\_file() subroutine to save the specified
       file.  The plugin will then be called at pluginIO() to "open"
       the file, and then to read the file data.
       Note, if you are dealing with a virtual file, the "open" operation
       is something the plugin does internally and it doesn't necessarily
       mean opening a file on the filesystem.  For example in the case of
       the bpipe-fd.c program, it initiates a pipe to the requested program.
       Finally when the plugin signals to Bacula that all the data was read,
       Bacula will call the plugin with the "close" pluginIO() function.
\end{enumerate}


\subsection{endBackupFile(bpContext *ctx)}
Called at the end of backing up a file.  If the plugin's work
is done, it should return bRC\_OK.  If the plugin wishes to create another
file and back it up, then it must return bRC\_More (not yet implemented).
This is probably a good time to release any malloc()ed memory you used to
pass back filenames.

\subsection{startRestoreFile(bpContext *ctx, const char *cmd)}
Not implemented.


\subsection{endRestoreFile(bpContext *ctx)}
Called when done restoring a file.

\subsection{pluginIO(bpContext *ctx, struct io\_pkt *io)}
Called to do the input (backup) or output (restore) of data from or to a
file. 

\begin{verbatim}
 enum {
   IO_OPEN = 1,
   IO_READ = 2,
   IO_WRITE = 3,
   IO_CLOSE = 4,
   IO_SEEK = 5
};

struct io_pkt {
   int32_t func;                      /* Function code */
   int32_t count;                     /* read/write count */
   mode_t mode;                       /* permissions for created files */
   int32_t flags;                     /* open flags (e.g. O_WRONLY ...) */
   char *buf;                         /* read/write buffer */
   int32_t status;                    /* return status */
   int32_t io_errno;                  /* errno code */
   int32_t whence;
   boffset_t offset;
};
\end{verbatim}


\subsection{createFile(bpContext *ctx, struct restore\_pkt *rp)}
Called to create a file during a Restore job before restoring the data. The data in the 
restore\_pkt is passed to the plugin and is based on the data that was
originally given by the plugin during the backup and the current user
restore settings (e.g. where, RegexWhere, replace).  This allows the
plugin to first create a file (if necessary) so that the data can
be transmitted to it.  The next call to the plugin will be a
pluginIO command with a request to open the file write-only.

\begin{verbatim}
 
struct restore_pkt {
   int32_t stream;                    /* attribute stream id */
   int32_t data_stream;               /* id of data stream to follow */
   int32_t type;                      /* file type FT */
   int32_t file_index;                /* file index */
   int32_t LinkFI;                    /* file index to data if hard link */
   uid_t uid;                         /* userid */
   struct stat statp;                 /* decoded stat packet */
   const char *attrEx;                /* extended attributes if any */
   const char *ofname;                /* output filename */
   const char *olname;                /* output link name */
   const char *where;                 /* where */
   const char *RegexWhere;            /* regex where */
   int replace;                       /* replace flag */
};
\end{verbatim}

\subsection{setFileAttributes(bpContext *ctx, struct restore\_pkt *rp)}
This is call not yet implemented.

\begin{verbatim}
struct restore_pkt {
   int32_t stream;                    /* attribute stream id */
   int32_t data_stream;               /* id of data stream to follow */
   int32_t type;                      /* file type FT */
   int32_t file_index;                /* file index */
   int32_t LinkFI;                    /* file index to data if hard link */
   uid_t uid;                         /* userid */
   struct stat statp;                 /* decoded stat packet */
   const char *attrEx;                /* extended attributes if any */
   const char *ofname;                /* output filename */
   const char *olname;                /* output link name */
   const char *where;                 /* where */
   const char *RegexWhere;            /* regex where */
   int replace;                       /* replace flag */
};
\end{verbatim}