From c638f142724c677c5c54eb136d77abbf59ff1bda Mon Sep 17 00:00:00 2001 From: Eric Bollengier Date: Mon, 23 Jan 2012 14:11:38 +0100 Subject: [PATCH] Add bvfs doc --- docs/manuals/en/developers/gui-interface.tex | 206 +++++++++++++++++-- 1 file changed, 189 insertions(+), 17 deletions(-) diff --git a/docs/manuals/en/developers/gui-interface.tex b/docs/manuals/en/developers/gui-interface.tex index 218f5af5..6c9f6668 100644 --- a/docs/manuals/en/developers/gui-interface.tex +++ b/docs/manuals/en/developers/gui-interface.tex @@ -107,26 +107,198 @@ in: \lt{bacula-source/src/wx-console} To help developers of restore GUI interfaces, we have added new \textsl{dot commands} that permit browsing the catalog in a very simple way. + +Bat has now a bRestore panel that uses Bvfs to display files and +directories. + +\begin{figure}[htbp] + \centering + \includegraphics[width=12cm]{\idir bat-brestore} + \label{fig:batbrestore} + \caption{Bat Brestore Panel} +\end{figure} + +\texttt{Important}, the Bvfs module does not yet work correctly with BaseJobs, +Copy and Migration jobs. + +\medskip +This project was funded by Bacula Systems. + +\subsection*{General notes} + \begin{itemize} -\item \texttt{.bvfs\_update [jobid=x,y,z]} This command is required to update - the Bvfs cache in the catalog. You need to run it before any access to the - Bvfs layer. - -\item \texttt{.bvfs\_lsdirs jobid=x,y,z path=/path | pathid=101} This command - will list all directories in the specified \texttt{path} or - \texttt{pathid}. Using \texttt{pathid} avoids problems with character - encoding of path/filenames. - -\item \texttt{.bvfs\_lsfiles jobid=x,y,z path=/path | pathid=101} This command - will list all files in the specified \texttt{path} or \texttt{pathid}. Using - \texttt{pathid} avoids problems with character encoding. +\item All fields are separated by a tab +\item You can specify \texttt{limit=} and \texttt{offset=} to list smoothly + records in very big directories +\item All operations (except cache creation) are designed to run instantly +\item At this time, Bvfs works faster on PostgreSQL than MySQL catalog. If you + can contribute new faster SQL queries we will be happy, else don't complain + about speed. +\item The cache creation is dependent of the number of directories. As Bvfs + shares information accross jobs, the first creation can be slow +\item All fields are separated by a tab +\item Due to potential encoding problem, it's advised to allways use pathid in + queries. \end{itemize} -You can use \texttt{limit=xxx} and \texttt{offset=yyy} to limit the amount of -data that will be displayed. +\subsection*{Get dependent jobs from a given JobId} + +Bvfs allows you to query the catalog against any combination of jobs. You +can combine all Jobs and all FileSet for a Client in a single session. + +To get all JobId needed to restore a particular job, you can use the +\texttt{.bvfs\_get\_jobids} command. + +\begin{verbatim} +.bvfs_get_jobids jobid=num [all] +\end{verbatim} + +\begin{verbatim} +.bvfs_get_jobids jobid=10 +1,2,5,10 +.bvfs_get_jobids jobid=10 all +1,2,3,5,10 +\end{verbatim} + +In this example, a normal restore will need to use JobIds 1,2,5,10 to +compute a complete restore of the system. + +With the \texttt{all} option, the Director will use all defined FileSet for +this client. + +\subsection*{Generating Bvfs cache} + +The \texttt{.bvfs\_update} command computes the directory cache for jobs +specified in argument, or for all jobs if unspecified. + +\begin{verbatim} +.bvfs_update [jobid=numlist] +\end{verbatim} + +Example: +\begin{verbatim} +.bvfs_update jobid=1,2,3 +\end{verbatim} + +You can run the cache update process in a RunScript after the catalog backup. + +\subsection*{Get all versions of a specific file} + +Bvfs allows you to find all versions of a specific file for a given Client with +the \texttt{.bvfs\_version} command. To avoid problems with encoding, this +function uses only PathId and FilenameId. The jobid argument is mandatory but +unused. + +\begin{verbatim} +.bvfs_versions client=filedaemon pathid=num filenameid=num jobid=1 +PathId FilenameId FileId JobId LStat Md5 VolName Inchanger +PathId FilenameId FileId JobId LStat Md5 VolName Inchanger +... +\end{verbatim} + +Example: + +\begin{verbatim} +.bvfs_versions client=localhost-fd pathid=1 fnid=47 jobid=1 +1 47 52 12 gD HRid IGk D Po Po A P BAA I A /uPgWaxMgKZlnMti7LChyA Vol1 1 +\end{verbatim} + +\subsection*{List directories} + +Bvfs allows you to list directories in a specific path. +\begin{verbatim} +.bvfs_lsdirs pathid=num path=/apath jobid=numlist limit=num offset=num +PathId FilenameId FileId JobId LStat Path +PathId FilenameId FileId JobId LStat Path +PathId FilenameId FileId JobId LStat Path +... +\end{verbatim} + +You need to \texttt{pathid} or \texttt{path}. Using \texttt{path=""} will list +``/'' on Unix and all drives on Windows. If FilenameId is 0, the record +listed is a directory. + +\begin{verbatim} +.bvfs_lsdirs pathid=4 jobid=1,11,12 +4 0 0 0 A A A A A A A A A A A A A A . +5 0 0 0 A A A A A A A A A A A A A A .. +3 0 0 0 A A A A A A A A A A A A A A regress/ +\end{verbatim} + +In this example, to list directories present in \texttt{regress/}, you can use +\begin{verbatim} +.bvfs_lsdirs pathid=3 jobid=1,11,12 +3 0 0 0 A A A A A A A A A A A A A A . +4 0 0 0 A A A A A A A A A A A A A A .. +2 0 0 0 A A A A A A A A A A A A A A tmp/ +\end{verbatim} + +\subsection*{List files} + +Bvfs allows you to list files in a specific path. +\begin{verbatim} +.bvfs_lsfiles pathid=num path=/apath jobid=numlist limit=num offset=num +PathId FilenameId FileId JobId LStat Path +PathId FilenameId FileId JobId LStat Path +PathId FilenameId FileId JobId LStat Path +... +\end{verbatim} + +You need to \texttt{pathid} or \texttt{path}. Using \texttt{path=""} will list +``/'' on Unix and all drives on Windows. If FilenameId is 0, the record listed +is a directory. + +\begin{verbatim} +.bvfs_lsfiles pathid=4 jobid=1,11,12 +4 0 0 0 A A A A A A A A A A A A A A . +5 0 0 0 A A A A A A A A A A A A A A .. +1 0 0 0 A A A A A A A A A A A A A A regress/ +\end{verbatim} + +In this example, to list files present in \texttt{regress/}, you can use +\begin{verbatim} +.bvfs_lsfiles pathid=1 jobid=1,11,12 +1 47 52 12 gD HRid IGk BAA I BMqcPH BMqcPE BMqe+t A titi +1 49 53 12 gD HRid IGk BAA I BMqe/K BMqcPE BMqe+t B toto +1 48 54 12 gD HRie IGk BAA I BMqcPH BMqcPE BMqe+3 A tutu +1 45 55 12 gD HRid IGk BAA I BMqe/K BMqcPE BMqe+t B ficheriro1.txt +1 46 56 12 gD HRie IGk BAA I BMqe/K BMqcPE BMqe+3 D ficheriro2.txt +\end{verbatim} + +\subsection*{Restore set of files} + +Bvfs allows you to create a SQL table that contains files that you want to +restore. This table can be provided to a restore command with the file option. + +\begin{verbatim} +.bvfs_restore fileid=numlist dirid=numlist hardlink=numlist path=b2num +OK +restore file=?b2num ... +\end{verbatim} + +To include a directory (with \texttt{dirid}), Bvfs needs to run a query to +select all files. This query could be time consuming. + +\texttt{hardlink} list is always composed of a serie of two numbers (jobid, +fileindex). This information can be found in the LinkFI field of the LStat +packet. + +The \texttt{path} argument represents the name of the table that Bvfs will +store results. The format of this table is \texttt{b2[0-9]+}. (Should start by +b2 and followed by digits). + +Example: + +\begin{verbatim} +.bvfs_restore fileid=1,2,3,4 hardlink=10,15,10,20 jobid=10 path=b20001 +OK +\end{verbatim} + +\subsection*{Cleanup after Restore} + +To drop the table used by the restore command, you can use the +\texttt{.bvfs\_cleanup} command. \begin{verbatim} -* .bvfs_update jobid=1,2 -* .bvfs_update -* .bvfs_lsdir path=/ jobid=1,2 +.bvfs_cleanup path=b20001 \end{verbatim} -- 2.39.5