4 \chapter*{Implementing a GUI Interface}
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}
11 \index[general]{General }
12 \addcontentsline{toc}{subsection}{General}
14 This document is intended mostly for developers who wish to develop a new GUI
15 interface to {\bf Bacula}.
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}
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.
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}
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:
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
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
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}
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.
63 static BSOCK *UA_sock = NULL;
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) {
73 jcr.dir_bsock = UA_sock;
74 if (!authenticate_director(\&jcr, dir)) {
75 fprintf(stderr, "ERR=%s", UA_sock->msg);
79 read_and_process_input(stdin, UA_sock);
81 bnet_sig(UA_sock, BNET_TERMINATE); /* send EOF */
88 Then the read\_and\_process\_input routine looks like the following:
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;
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}
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.
111 Bat has now a bRestore panel that uses Bvfs to display files and
114 \bsysimageH{bat-brestore}{Bat Brestore Panel}{fig:batbrestore}
115 %% \begin{figure}[htbp]
117 %% \includegraphics[width=12cm]{\idir bat-brestore}
118 %% \label{fig:batbrestore}
119 %% \caption{Bat Brestore Panel}
122 The Bvfs module works correctly with BaseJobs, Copy and Migration jobs.
125 This project was funded by Bacula Systems.
127 \subsection*{General notes}
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
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
144 \subsection*{Get dependent jobs from a given JobId}
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.
149 To get all JobId needed to restore a particular job, you can use the
150 \texttt{.bvfs\_get\_jobids} command.
153 .bvfs_get_jobids jobid=num [all]
157 .bvfs_get_jobids jobid=10
159 .bvfs_get_jobids jobid=10 all
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.
166 With the \texttt{all} option, the Director will use all defined FileSet for
169 \subsection*{Generating Bvfs cache}
171 The \texttt{.bvfs\_update} command computes the directory cache for jobs
172 specified in argument, or for all jobs if unspecified.
175 .bvfs_update [jobid=numlist]
180 .bvfs_update jobid=1,2,3
183 You can run the cache update process in a RunScript after the catalog backup.
185 \subsection*{Get all versions of a specific file}
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
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
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
206 \subsection*{List directories}
208 Bvfs allows you to list directories in a specific path.
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
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.
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/
228 In this example, to list directories present in \texttt{regress/}, you can use
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/
236 \subsection*{List files}
238 Bvfs allows you to list files in a specific path.
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
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
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/
258 In this example, to list files present in \texttt{regress/}, you can use
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
268 \subsection*{Restore set of files}
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.
274 .bvfs_restore fileid=numlist dirid=numlist hardlink=numlist path=b2num
276 restore file=?b2num ...
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.
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
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).
293 .bvfs_restore fileid=1,2,3,4 hardlink=10,15,10,20 jobid=10 path=b20001
297 \subsection*{Cleanup after Restore}
299 To drop the table used by the restore command, you can use the
300 \texttt{.bvfs\_cleanup} command.
303 .bvfs_cleanup path=b20001
306 \subsection*{Clearing the BVFS Cache}
308 To clear the BVFS cache, you can use the \texttt{.bvfs\_clear\_cache} command.
311 .bvfs_clear_cache yes