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 9This document is intended mostly for developers who wish to develop a new \acs{GUI} 10interface 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 16Until now, I have kept all the Catalog code in the Directory (with the 17exception of \btool{dbcheck} and \btool{bscan}). This is because at some point I would like to 18add user level security and access. If we have code spread everywhere such as 19in a \acs{GUI} this will be more difficult. The other advantage is that any code you 20add to the Director is automatically available to both the \texttt{tty} console program 21and the WX program. The major disadvantage is it increases the size of the 22code -- 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 28Interfacing to an interactive program such as \bacula{} can be very difficult 29because the interfacing program must interpret all the prompts that may come. 30This can be next to impossible. There are are a number of ways that \bacula{} is 31designed to facilitate this: 32 33\begin{bitemize} 34\item The \bacula{} network protocol is packet based, and thus pieces of 35information 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 38than data. 39\item The \bDirector{} has a number of commands that are non-interactive. They 40all begin with a period, and provide things such as the list of all Jobs, 41list of all Clients, list of all Pools, list of all Storage, \ldots{} Thus the \acs{GUI} 42interface can get to virtually all information that the Director has in a 43deterministic way. See \bfilename{\bbracket{bacula-source}/src/dird/ua\_dotcmds.c} for 44more details on this. 45\item Most console commands allow all the arguments to be specified on the 46command line: e.g. \bcommand{run job=NightlyBackup level=Full} 47\end{bitemize} 48 49One of the first things to overcome is to be able to establish a conversation 50with the Director. Although you can write all your own code, it is probably 51easier to use the \bacula{} subroutines. The following code is used by the 52Console program to begin a conversation. 53 54\begin{bVerbatim} 55static BSOCK *UA_sock = NULL; 56static 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 79Then 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 88For a \acs{GUI} program things will be a bit more complicated. Basically in the very 89inner loop, you will need to check and see if any output is available on the 90UA\_sock. For an example, please take a look at the WX \acs{GUI} interface code 91in: \lt{bacula-source/src/wx-console} 92 93\section{Bvfs API} 94\label{blb:sec:bvfs} 95 96To 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 100Bat has now a bRestore panel that uses Bvfs to display files and 101directories. 102 103\bimageH{bat-brestore}{Bat Brestore Panel}{blb:fig:batbrestore} 104 105The Bvfs module works correctly with BaseJobs, Copy and Migration jobs. 106 107\medskip 108This 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 126Bvfs allows you to query the catalog against any combination of jobs. You 127can combine all Jobs and all FileSet for a Client in a single session. 128 129To 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 1381,2,5,10 139.bvfs_get_jobids jobid=10 all 1401,2,3,5,10 141\end{bVerbatim} 142 143In this example, a normal restore will need to use JobIds 1,2,5,10 to 144compute a complete restore of the system. 145 146With the \texttt{all} option, the Director will use all defined FileSet for 147this client. 148 149\subsection*{Delete a Catalog File Record} 150In 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 160The \bcommand{.bvfs\_update} command computes the directory cache for jobs 161specified in argument, or for all jobs if unspecified. 162 163\begin{bVerbatim} 164.bvfs_update [jobid=numlist] 165\end{bVerbatim} 166 167Example: 168\begin{bVerbatim} 169.bvfs_update jobid=1,2,3 170\end{bVerbatim} 171 172You can run the cache update process in a RunScript after the catalog backup. 173 174\subsection*{Get all versions of a specific file} 175 176Bvfs allows you to find all versions of a specific file for a given Client with 177the \bcommand{.bvfs\_version} command. To avoid problems with encoding, this 178function uses only PathId and FilenameId. The jobid argument is mandatory but 179unused. 180 181\begin{bVerbatim} 182.bvfs_versions client=filedaemon pathid=num filenameid=num jobid=1 183PathId FilenameId FileId JobId LStat Md5 VolName Inchanger 184PathId FilenameId FileId JobId LStat Md5 VolName Inchanger 185... 186\end{bVerbatim} 187 188Example: 189 190\begin{bVerbatim} 191.bvfs_versions client=localhost-fd pathid=1 fnid=47 jobid=1 1921 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 197Bvfs 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 200PathId FilenameId FileId JobId LStat Path 201PathId FilenameId FileId JobId LStat Path 202PathId FilenameId FileId JobId LStat Path 203... 204\end{bVerbatim} 205 206You 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 208listed is a directory. 209 210\begin{bVerbatim} 211.bvfs_lsdirs pathid=4 jobid=1,11,12 2124 0 0 0 A A A A A A A A A A A A A A . 2135 0 0 0 A A A A A A A A A A A A A A .. 2143 0 0 0 A A A A A A A A A A A A A A regress/ 215\end{bVerbatim} 216 217In this example, to list directories present in \texttt{regress/}, you can use 218\begin{bVerbatim} 219.bvfs_lsdirs pathid=3 jobid=1,11,12 2203 0 0 0 A A A A A A A A A A A A A A . 2214 0 0 0 A A A A A A A A A A A A A A .. 2222 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 227Bvfs 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 230PathId FilenameId FileId JobId LStat Path 231PathId FilenameId FileId JobId LStat Path 232PathId FilenameId FileId JobId LStat Path 233... 234\end{bVerbatim} 235 236You 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 238is a directory. 239 240\begin{bVerbatim} 241.bvfs_lsfiles pathid=4 jobid=1,11,12 2424 0 0 0 A A A A A A A A A A A A A A . 2435 0 0 0 A A A A A A A A A A A A A A .. 2441 0 0 0 A A A A A A A A A A A A A A regress/ 245\end{bVerbatim} 246 247In this example, to list files present in \texttt{regress/}, you can use 248\begin{bVerbatim} 249.bvfs_lsfiles pathid=1 jobid=1,11,12 2501 47 52 12 gD HRid IGk BAA I BMqcPH BMqcPE BMqe+t A titi 2511 49 53 12 gD HRid IGk BAA I BMqe/K BMqcPE BMqe+t B toto 2521 48 54 12 gD HRie IGk BAA I BMqcPH BMqcPE BMqe+3 A tutu 2531 45 55 12 gD HRid IGk BAA I BMqe/K BMqcPE BMqe+t B ficheriro1.txt 2541 46 56 12 gD HRie IGk BAA I BMqe/K BMqcPE BMqe+3 D ficheriro2.txt 255\end{bVerbatim} 256 257\subsection*{Restore set of files} 258 259Bvfs allows you to create a SQL table that contains files (as well as plugin objects) that you want to 260restore. This table can be provided to a restore command with the file option. 261 262\begin{bVerbatim} 263.bvfs_restore fileid=numlist dirid=numlist path=b2num objectid=numlist 264OK 265restore file=?b2num ... 266\end{bVerbatim} 267 268To include a directory (with \texttt{dirid}), Bvfs needs to run a query to 269select all files. This query could be time consuming. 270 271The \texttt{path} argument represents the name of the table that Bvfs will 272store results. The format of this table is \texttt{b2[0-9]+}. (Should start by 273b2 and followed by digits). 274 275Example: 276 277\begin{bVerbatim} 278.bvfs_restore fileid=1,2,3,4 jobid=10 path=b20001 objectid=1,2,3 279OK 280\end{bVerbatim} 281 282\subsection*{Cleanup after Restore} 283 284To drop the table used by the restore command, you can use the 285\bcommand{.bvfs\_cleanup} command. 286 287\begin{bVerbatim} 288.bvfs_cleanup path=b20001 289\end{bVerbatim} 290 291\subsection*{Clearing the BVFS Cache} 292 293To clear the BVFS cache, you can use the \bcommand{.bvfs\_clear\_cache} command. 294 295\begin{bVerbatim} 296.bvfs_clear_cache yes 297OK 298\end{bVerbatim} 299 300\subsection*{Decode the LStat Attribute} 301 302\begin{bVerbatim} 303*.bvfs_decode_lstat lstat="A A IHA A A A A A BAA B BXTDon BXTDon BXTDon A A C" 304st_nlink=0 305st_mode=33216 306st_uid=0 307st_gid=0 308st_size=0 309st_blocks=1 310st_ino=0 311st_ctime=1464613415 312st_mtime=1464613415 313st_atime=1464613415 314st_dev=0 315LinkFI=0 316\end{bVerbatim} 317 318