git.sur5r.net Git - bacula/docs/blob - docs/manuals/en/developers/gui-interface.tex

   1 %%
   2 %%
   3
   4 \chapter*{Implementing a GUI Interface}
   5 \label{_ChapterStart}
   6 \index[general]{Interface!Implementing a Bacula GUI }
   7 \index[general]{Implementing a Bacula GUI Interface }
   8 \addcontentsline{toc}{section}{Implementing a Bacula GUI Interface}
   9
  10 \section{General}
  11 \index[general]{General }
  12 \addcontentsline{toc}{subsection}{General}
  13
  14 This document is intended mostly for developers who wish to develop a new GUI
  15 interface to {\bf Bacula}.
  16
  17 \subsection{Minimal Code in Console Program}
  18 \index[general]{Program!Minimal Code in Console }
  19 \index[general]{Minimal Code in Console Program }
  20 \addcontentsline{toc}{subsubsection}{Minimal Code in Console Program}
  21
  22 Until now, I have kept all the Catalog code in the Directory (with the
  23 exception of dbcheck and bscan). This is because at some point I would like to
  24 add user level security and access. If we have code spread everywhere such as
  25 in a GUI this will be more difficult. The other advantage is that any code you
  26 add to the Director is automatically available to both the tty console program
  27 and the WX program. The major disadvantage is it increases the size of the
  28 code -- however, compared to Networker the Bacula Director is really tiny.
  29
  30 \subsection{GUI Interface is Difficult}
  31 \index[general]{GUI Interface is Difficult }
  32 \index[general]{Difficult!GUI Interface is }
  33 \addcontentsline{toc}{subsubsection}{GUI Interface is Difficult}
  34
  35 Interfacing to an interactive program such as Bacula can be very difficult
  36 because the interfacing program must interpret all the prompts that may come.
  37 This can be next to impossible. There are are a number of ways that Bacula is
  38 designed to facilitate this:
  39
  40 \begin{itemize}
  41 \item The Bacula network protocol is packet based, and  thus pieces of
  42 information sent can be ASCII or binary.
  43 \item The packet interface permits knowing where the end of  a list is.
  44 \item The packet interface permits special ``signals''  to be passed rather
  45 than data.
  46 \item The Director has a number of commands that are  non-interactive. They
  47 all begin with a period,  and provide things such as the list of all Jobs,
  48 list of all Clients, list of all Pools, list of  all Storage, ... Thus the GUI
  49 interface can get  to virtually all information that the Director has  in a
  50 deterministic way. See  \lt{}bacula-source\gt{}/src/dird/ua\_dotcmds.c for
  51 more details on this.
  52 \item Most console commands allow all the arguments to  be specified on the
  53 command line: e.g.  {\bf run job=NightlyBackup level=Full}
  54 \end{itemize}
  55
  56 One of the first things to overcome is to be able to establish a conversation
  57 with the Director. Although you can write all your own code, it is probably
  58 easier to use the Bacula subroutines. The following code is used by the
  59 Console program to begin a conversation.
  60
  61 \footnotesize
  62 \begin{verbatim}
  63 static BSOCK *UA_sock = NULL;
  64 static JCR *jcr;
  65 ...
  66   read-your-config-getting-address-and-pasword;
  67   UA_sock = bnet_connect(NULL, 5, 15, "Director daemon", dir->address,
  68                           NULL, dir->DIRport, 0);
  69    if (UA_sock == NULL) {
  70       terminate_console(0);
  71       return 1;
  72    }
  73    jcr.dir_bsock = UA_sock;
  74    if (!authenticate_director(\&jcr, dir)) {
  75       fprintf(stderr, "ERR=%s", UA_sock->msg);
  76       terminate_console(0);
  77       return 1;
  78    }
  79    read_and_process_input(stdin, UA_sock);
  80    if (UA_sock) {
  81       bnet_sig(UA_sock, BNET_TERMINATE); /* send EOF */
  82       bnet_close(UA_sock);
  83    }
  84    exit 0;
  85 \end{verbatim}
  86 \normalsize
  87
  88 Then the read\_and\_process\_input routine looks like the following:
  89
  90 \footnotesize
  91 \begin{verbatim}
  92    get-input-to-send-to-the-Director;
  93    bnet_fsend(UA_sock, "%s", input);
  94    stat = bnet_recv(UA_sock);
  95    process-output-from-the-Director;
  96 \end{verbatim}
  97 \normalsize
  98
  99 For a GUI program things will be a bit more complicated. Basically in the very
 100 inner loop, you will need to check and see if any output is available on the
 101 UA\_sock. For an example, please take a look at the WX GUI interface code
 102 in: \lt{bacula-source/src/wx-console}
 103
 104 \section{Bvfs API}
 105 \label{sec:bvfs}
 106
 107 To help developers of restore GUI interfaces, we have added new \textsl{dot
 108   commands} that permit browsing the catalog in a very simple way.
 109
 110
 111 Bat has now a bRestore panel that uses Bvfs to display files and
 112 directories.
 113
 114 \begin{figure}[htbp]
 115   \centering
 116   \includegraphics[width=12cm]{\idir bat-brestore}
 117   \label{fig:batbrestore}
 118   \caption{Bat Brestore Panel}
 119 \end{figure}
 120
 121 \texttt{Important}, the Bvfs module does not yet work correctly with BaseJobs,
 122 Copy and Migration jobs.
 123
 124 \medskip
 125 This project was funded by Bacula Systems.
 126
 127 \subsection*{General notes}
 128
 129 \begin{itemize}
 130 \item All fields are separated by a tab
 131 \item You can specify \texttt{limit=} and \texttt{offset=} to list smoothly
 132   records in very big directories
 133 \item All operations (except cache creation) are designed to run instantly
 134 \item At this time, Bvfs works faster on PostgreSQL than MySQL catalog. If you
 135   can contribute new faster SQL queries we will be happy, else don't complain
 136   about speed.
 137 \item The cache creation is dependent of the number of directories. As Bvfs
 138   shares information accross jobs, the first creation can be slow
 139 \item All fields are separated by a tab
 140 \item Due to potential encoding problem, it's advised to allways use pathid in
 141   queries.
 142 \end{itemize}
 143
 144 \subsection*{Get dependent jobs from a given JobId}
 145
 146 Bvfs allows you to query the catalog against any combination of jobs. You
 147 can combine all Jobs and all FileSet for a Client in a single session.
 148
 149 To get all JobId needed to restore a particular job, you can use the
 150 \texttt{.bvfs\_get\_jobids} command.
 151
 152 \begin{verbatim}
 153 .bvfs_get_jobids jobid=num [all]
 154 \end{verbatim}
 155
 156 \begin{verbatim}
 157 .bvfs_get_jobids jobid=10
 158 1,2,5,10
 159 .bvfs_get_jobids jobid=10 all
 160 1,2,3,5,10
 161 \end{verbatim}
 162
 163 In this example, a normal restore will need to use JobIds 1,2,5,10 to
 164 compute a complete restore of the system.
 165
 166 With the \texttt{all} option, the Director will use all defined FileSet for
 167 this client.
 168
 169 \subsection*{Generating Bvfs cache}
 170
 171 The \texttt{.bvfs\_update} command computes the directory cache for jobs
 172 specified in argument, or for all jobs if unspecified.
 173
 174 \begin{verbatim}
 175 .bvfs_update [jobid=numlist]
 176 \end{verbatim}
 177
 178 Example:
 179 \begin{verbatim}
 180 .bvfs_update jobid=1,2,3
 181 \end{verbatim}
 182
 183 You can run the cache update process in a RunScript after the catalog backup.
 184
 185 \subsection*{Get all versions of a specific file}
 186
 187 Bvfs allows you to find all versions of a specific file for a given Client with
 188 the \texttt{.bvfs\_version} command. To avoid problems with encoding, this
 189 function uses only PathId and FilenameId. The jobid argument is mandatory but
 190 unused.
 191
 192 \begin{verbatim}
 193 .bvfs_versions client=filedaemon pathid=num filenameid=num jobid=1
 194 PathId FilenameId FileId JobId LStat Md5 VolName Inchanger
 195 PathId FilenameId FileId JobId LStat Md5 VolName Inchanger
 196 ...
 197 \end{verbatim}
 198
 199 Example:
 200
 201 \begin{verbatim}
 202 .bvfs_versions client=localhost-fd pathid=1 fnid=47 jobid=1
 203 1  47  52  12  gD HRid IGk D Po Po A P BAA I A   /uPgWaxMgKZlnMti7LChyA  Vol1  1
 204 \end{verbatim}
 205
 206 \subsection*{List directories}
 207
 208 Bvfs allows you to list directories in a specific path.
 209 \begin{verbatim}
 210 .bvfs_lsdirs pathid=num path=/apath jobid=numlist limit=num offset=num
 211 PathId  FilenameId  FileId  JobId  LStat  Path
 212 PathId  FilenameId  FileId  JobId  LStat  Path
 213 PathId  FilenameId  FileId  JobId  LStat  Path
 214 ...
 215 \end{verbatim}
 216
 217 You need to \texttt{pathid} or \texttt{path}. Using \texttt{path=""} will list
 218 ``/'' on Unix and all drives on Windows.  If FilenameId is 0, the record
 219 listed is a directory.
 220
 221 \begin{verbatim}
 222 .bvfs_lsdirs pathid=4 jobid=1,11,12
 223 4       0       0       0       A A A A A A A A A A A A A A     .
 224 5       0       0       0       A A A A A A A A A A A A A A     ..
 225 3       0       0       0       A A A A A A A A A A A A A A     regress/
 226 \end{verbatim}
 227
 228 In this example, to list directories present in \texttt{regress/}, you can use
 229 \begin{verbatim}
 230 .bvfs_lsdirs pathid=3 jobid=1,11,12
 231 3       0       0       0       A A A A A A A A A A A A A A     .
 232 4       0       0       0       A A A A A A A A A A A A A A     ..
 233 2       0       0       0       A A A A A A A A A A A A A A     tmp/
 234 \end{verbatim}
 235
 236 \subsection*{List files}
 237
 238 Bvfs allows you to list files in a specific path.
 239 \begin{verbatim}
 240 .bvfs_lsfiles pathid=num path=/apath jobid=numlist limit=num offset=num
 241 PathId  FilenameId  FileId  JobId  LStat  Path
 242 PathId  FilenameId  FileId  JobId  LStat  Path
 243 PathId  FilenameId  FileId  JobId  LStat  Path
 244 ...
 245 \end{verbatim}
 246
 247 You need to \texttt{pathid} or \texttt{path}. Using \texttt{path=""} will list
 248 ``/'' on Unix and all drives on Windows. If FilenameId is 0, the record listed
 249 is a directory.
 250
 251 \begin{verbatim}
 252 .bvfs_lsfiles pathid=4 jobid=1,11,12
 253 4       0       0       0       A A A A A A A A A A A A A A     .
 254 5       0       0       0       A A A A A A A A A A A A A A     ..
 255 1       0       0       0       A A A A A A A A A A A A A A     regress/
 256 \end{verbatim}
 257
 258 In this example, to list files present in \texttt{regress/}, you can use
 259 \begin{verbatim}
 260 .bvfs_lsfiles pathid=1 jobid=1,11,12
 261 1   47   52   12    gD HRid IGk BAA I BMqcPH BMqcPE BMqe+t A     titi
 262 1   49   53   12    gD HRid IGk BAA I BMqe/K BMqcPE BMqe+t B     toto
 263 1   48   54   12    gD HRie IGk BAA I BMqcPH BMqcPE BMqe+3 A     tutu
 264 1   45   55   12    gD HRid IGk BAA I BMqe/K BMqcPE BMqe+t B     ficheriro1.txt
 265 1   46   56   12    gD HRie IGk BAA I BMqe/K BMqcPE BMqe+3 D     ficheriro2.txt
 266 \end{verbatim}
 267
 268 \subsection*{Restore set of files}
 269
 270 Bvfs allows you to create a SQL table that contains files that you want to
 271 restore. This table can be provided to a restore command with the file option.
 272
 273 \begin{verbatim}
 274 .bvfs_restore fileid=numlist dirid=numlist hardlink=numlist path=b2num
 275 OK
 276 restore file=?b2num ...
 277 \end{verbatim}
 278
 279 To include a directory (with \texttt{dirid}), Bvfs needs to run a query to
 280 select all files. This query could be time consuming.
 281
 282 \texttt{hardlink} list is always composed of a serie of two numbers (jobid,
 283 fileindex). This information can be found in the LinkFI field of the LStat
 284 packet.
 285
 286 The \texttt{path} argument represents the name of the table that Bvfs will
 287 store results. The format of this table is \texttt{b2[0-9]+}. (Should start by
 288 b2 and followed by digits).
 289
 290 Example:
 291
 292 \begin{verbatim}
 293 .bvfs_restore fileid=1,2,3,4 hardlink=10,15,10,20 jobid=10 path=b20001
 294 OK
 295 \end{verbatim}
 296
 297 \subsection*{Cleanup after Restore}
 298
 299 To drop the table used by the restore command, you can use the
 300 \texttt{.bvfs\_cleanup} command.
 301
 302 \begin{verbatim}
 303 .bvfs_cleanup path=b20001
 304 \end{verbatim}
 305
 306 \subsection*{Clearing the BVFS Cache}
 307
 308 To clear the BVFS cache, you can use the \texttt{.bvfs\_clear_cache} command.
 309
 310 \begin{verbatim}
 311 .bvfs_clear_cache yes
 312 OK
 313 \end{verbatim}