From 3071e06e8fcce9d89727b41054d373e3fb0fc5a5 Mon Sep 17 00:00:00 2001 From: Frank Bergkemper Date: Mon, 16 Dec 2013 14:51:46 +0100 Subject: [PATCH] bpipe plugin documentation --- manuals/en/main/howto.tex | 94 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 94 insertions(+) diff --git a/manuals/en/main/howto.tex b/manuals/en/main/howto.tex index 2f27787..bb03685 100644 --- a/manuals/en/main/howto.tex +++ b/manuals/en/main/howto.tex @@ -589,3 +589,97 @@ \subsubsection{Restores} Termination: Restore OK \end{bconsole} +\section{The bpipe Plugin} +\label{bpipe} + +The bpipe plugin is a generic pipe program, that simply transmits the data from a specified program to Bareos for backup, and +from Bareos to a specified program for restore. The purpose of the plugin is to provide an interface to any system program +for backup and restore. That allows you, for example, to do database backups without a local dump. By using different command +lines to bpipe, you can backup any kind of data (ASCII or binary) depending on the program called. + +The bpipe plugin is provided in the directory \path|src/plugins/filed/bpipe-fd.c| of the Bareos source distribution or by the +bareos-common binary package of your distributions repository and has to be installed on the client where the FileDaemon is running. + +The following line has to be present in your bareos-fd.conf, so the FileDaemon knows the path where to look for the plugin, +when it's called. + +\begin{bconfig}{bpipe fdconfig} +PluginDirectory = /usr/lib64/bareos/plugins +\end{bconfig} + +Please note that this is a very simple plugin that was written for demonstration and test purposes. It is and can be used +in production, but that was never intended. The bpipe plugin is so simple and flexible, you may call it the +"Swiss Army Knife" of the current existing plugins for Bareos. + +The bpipe plugin is specified in the Include section of your Job's FileSet resource in your bareos-dir.conf. + +\begin{bconfig}{bpipe fileset} +FileSet { + Name = "MyFileSet" + Include { + Options { + signature = MD5 + compression = gzip + } + Plugin = "bpipe:..." + } +} +\end{bconfig} + +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. The full syntax of the plugin directive as interpreted by the bpipe plugin is: + +\begin{bconfig}{bpipe directive} +Plugin = ":::" +\end{bconfig} + +\begin{description} +\item[plugin] is the name of the plugin with the trailing -fd.so stripped off, so in this case, we would put bpipe in the field. +\item[path] specifies the namespace, which for 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 /MySQL/mydump.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[command1] for the bpipe plugin specifies the "reader" program that is called by the plugin during backup to read the data. bpipe +will call this program by doing a popen on it. +\item[command2] for the bpipe plugin specifies the "writer" program that is called by the plugin during restore to write the data back +to the filesystem. +\end{description} + +Please note that the two items above describing the "reader" and "writer", these programs are "executed" by Bareos, which means +there is no shell inerpretation of any command line arguments you might use. If you want to use shell characters (redirection of input +or output, ...), then we recommend that you put your command or commands in a shell script and execute the script. In addition if you +backup a file with reader program, when running the writer program during the restore, Bareos will not automatically create the path +to the file. Either the path must exist, or you must explicitly do so with your command or in a shell script. + +Putting it all together, the full plugin directive line might look like the following: + +\begin{bconfig}{bpipe directive PostgreSQL dump} +Plugin = "bpipe:/POSTGRESQL/bareos.sql:pg_dumpall -U postgres:psql -U postgres" +\end{bconfig} + +This causes the File daemon to call bpipe plugin, which will write its data into the "pseudo" file \path|/POSTGRESQL/bareos.sql| by +calling the program \command{pg_dumpall -U postgres} to read the data during backup. The \command{pg_dumpall} command outputs all +the data for the database, 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 psql. When psql is called, it will read the data sent to it by +the plugin then write it back to the same database from which it came from. + +Here is a complete FileSet example, where first your \path|/home| is backed up and then a mysqldump is done. + +\begin{bconfig}{bpipe fileset MySQL dump} +FileSet { + Name = "" + Include = { + File = /home + Plugin = "bpipe:/MYSQL/:mysqldump -u --password= --opt --all-databases:mysql -u -p " + Options { + signature = MD5 + compression = gzip + } + } + Exclude { + } +} +\end{bconfig} + +Note: It is also possible to define more than one plugin directive in a FileSet to do several database dumps at once.