Debian Codegraph @

manuals/en/developers/gui-interface.tex

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