Debian Codegraph @

manuals/en/main/ui-traymonitor.tex

raw
1 \section{The Tray Monitor}
2 \label{blb:TrayMonitorChapter}
3 \index[general]{User Interfaces!Tray Monitor}
4 \index[general]{Tray Monitor}
5
6 The Tray Monitor program is a simplified graphical user interface intended to
7 be used with \acsp{GUI} providing a tray area, similar to Windows' Task Bar
8 information icon tray area. % TODO: what is this thing called in English?
9
10 It provides the capability to monitor all the core components of a \bacula{}
11 infrastructure, namely Directors, Storage Daemons and File Daemons. The Tray
12 Monitor program can be configured to monitor an arbitrary number of those
13 daemons, and it can show an icon indicating current activity of the monitored
14 daemon.
15
16 The Tray Monitor also has a built-in graphical configuration interface
17 (but it can, as all \bacula{} components, be configured with a plain text file)
18 and allows to initiate backup jobs through its context menu.
19
20 In addition, the Tray Monitor program can interactively or non-interactively
21 start jobs.
22
23 The latter functionality is particularly valuable if used in conjunction with
24 the capability of File Daemons to serve as proxy when connecting to a Director
25 needing a connection to the client to run a job.
26
27 \subsection{Installation}
28 When building the \bacula{} software from source, the Tray Monitor program will
29 be built similarly and under the same conditions as \bat{}, the \acl{BAT}, is.
30 In particular, it needs a Qt build environment.
31 \medskip
32
33 When installing the client software from packages, the Tray Monitor may be
34 packaged individually or along with some other console programs -- this is
35 a packager's decision. \baculasystems{}' Enterprise Edition packages the Tray
36 Monitor together with the \acs{GUI} console (\bat{}) on Linux, and with the client
37 installer on Windows.
38
39 The actual steps to install depend on the platform and the packages used.
40 A Windows Installer will typically allow to select the Tray Monitor for
41 installation in some tree view of components to be installed.
42 \medskip
43
44 The Tray Monitor program can be started whenever a \acs{GUI} session is initiated,
45 but care should be taken to use a configuration file that belongs to the
46 user who runs the \acs{GUI} session. In particular, having a default configuration
47 file with credentials allowing unrestricted Director access usable by
48 regular end users is to be avoided.
49
50
51 \subsection{Configuration}
52 The Tray Monitor program, unlike most other parts of the \bacula{} software, can
53 be run without a configuration file in place. In this case, the configuration
54 panel will be opened, allowing the user to configure the program according to
55 her needs.
56
57 With the Tray Monitor it is quite likely that individual users will have their
58 own configuration, i.e. a system-wide configuration file is not the
59 common way to run the program. This is because the Tray Monitor, to do its
60 work, needs access to backend components of the \bacula{} infrastructure, and
61 individual users will only be provided with restricted access by the
62 \bacula{} administration for security reasons.
63
64 For example, on a system shared by regular users and system administrators,
65 the non-privileged users should not be able to see all jobs that can be run
66 but only the ones relating to their own data, while a system administrator
67 probably needs to monitor all the components running on the machines under his
68 responsibility.
69
70 \subsubsection{\acs{GUI} Configuration}
71
72 When started without a configuration file, or when the ``Configure\ldots{}''
73 context menu item of the tray icon is clicked, the configuration window of
74 the \btool{Tray Monitor} program is shown. It consists of a tabbed view of
75 configuration pages and some buttons, which provide the following functionality:
76
77 \begin{bdescription}
78 \item[Save] to save the current state into a text file (see paragraph above).
79 \item[Cancel] to abort the operation, leave everything as it was, and close the
80 configuration panel.
81 \item[Password] to toggle between showing passwords on the current tab page
82 in clear or hidden. This is useful to keep passwords hidden against
83 observers, but still be able to check potentially complex and long
84 passwords when needed.
85 \item[(Add) Client] to add a new, empty client configuration tab.
86 \item[(Add) Storage] to add a new, empty storage configuration tab.
87 \item[(Add) Director] to add a new, empty director configuration tab.
88 \end{bdescription}
89
90 There will always be at least one tab to configure the identity of this Tray
91 Monitor instance itself. Configuration page tabs that represent Clients,
92 Storages, and Directors, will initially appear with a title of ``New \bbracket{Component}''
93 which will change to the name of the monitored component once that has been provided.
94
95 \subsubsection{The Monitor Configuration page}
96
97 This tab defines the identity of the Tray Monitor instance. It is always
98 available, cannot be removed, and there can only be one such tab. It contains
99 the following fields:
100
101 \begin{bdescription}
102 \item[Name] the name of this Tray Monitor instance. This name is
103 used to authenticate when connecting to any other \bacula{} daemon.\par
104 Note that, as usual with \bacula{}, the password used for authentication
105 is configured individually for each counterpart.\par
106 The name is a \textit{name-string} data type and allows
107 only a limited set of characters (essentially, \acs{ASCII} characters and numerals
108 plus basic interpunction) and is limited to a length of 127 characters.
109 \item[Refresh Interval] is used to set the number of seconds between refreshes
110 of status displays. Integer numbers between 5 and 9999 can be entered or
111 selected.
112 \item[Command Directory] allows to enter or select the path of a directory
113 which will be polled for command files. See below for details on how to
114 use this feature. % TODO: create link once the description exists
115 \item[Display Advanced Options] will enable a settings page to select
116 more Job options when the ``Run\ldots{}'' context menu item of the
117 \btool{Tray Monitor} program is selected. See below for more information. % TODO: link
118 \end{bdescription}
119
120 As usual for a \bacula{} component, unless the identity is configured the program
121 will not be very functional.
122
123 \subsubsection{Common elements}
124
125 A common layout is used throughout all the configuration pages for the
126 different \bacula{} Daemons. We will describe that first, before we look at
127 specific additional configuration items for Client and Director.
128
129 We have always two groups of settings and a waste bin icon. The waste bin is
130 used to delete the currently shown configuration from the Tray Monitor setup.
131
132 One group of settings is used to define the essential information to contact
133 and use the component, and one group to configure \acs{TLS}-related information. The
134 former contains some required fields, among them the connection and
135 authentication information, while the latter is optional.
136
137 We will not discuss the details of \acs{TLS} configuration here -- if \acs{TLS} is
138 required, the \bacula{} administrator will probably give detailed instructions
139 and has to provide at least the ``\acs{CA} Certificate File''. Simply put, leave the
140 ``Enabled'' check box in the \acs{TLS} section turned off unless detailed and
141 site-specific configuration information is provided. If it is enabled, the
142 selections in this group are critical and need to match what is configured
143 for the respective daemon.
144 \medskip
145
146 The General section contains the following elements common to Client,
147 Storage, and Director configuration pages:
148 \begin{bdescription}
149 \item[Name] to configure the name that is used to represent this component
150 in the Tray Monitor's user interface. This is a typical \bacula{} ``name-string''
151 with restrictions in length and usable character set (see above in the
152 ``Monitor Configuration'' description).
153 \item[Description] can hold a textual description of the component. It is
154 not used for any functionality, but rather to allow users to annotate their
155 configuration.\par
156 The length of the description text is limited to 512 characters, and it can
157 contain (nearly) any character as it's of the configuration data type
158 ``string''.
159 \item[Password] is used to configure the shared secret that authenticates
160 against the configured daemon. By default the text entered here is hidden, but
161 it is possible to toggle with clear-text display using the ``Password'' button
162 on the right.\par
163 The password is of \bacula{}'s ``password'' data type and as such can contain
164 up to 127 characters. \acs{ASCII} symbols, numerals, and some punctuation are
165 allowed here.
166 \item[Address] is the address at which the configured daemon can be contacted.
167 Usually, an \acs{IP}v4 address in dotted quad notation or a \acs{DNS} name is used.\par
168 Note that domain names should be fully qualified -- using plain host names
169 is strongly discouraged.\par
170 Support for \acs{IP}v6 addresses depends on how the Tray Monitor program was
171 built, but should be matching the \acs{IP}v6 support status of all other \bacula{}
172 programs resulting from the same build run.
173 \item[Port] represents the port number at which the daemon that is configured
174 to be monitored can be contacted. Integer numbers between 1 and 65535 are
175 allowed here. The default value shown in a new configuration page is the
176 default port number for the daemon type.\par
177 This value should only be modified in two cases:
178 \begin{benumerate}
179 \item When the \bacula{} administrator explicitly indicates that a specific,
180 non standard port number should be used.
181 \item When the File Daemon is configured for client-initiated backup. In this
182 case the address to use will usually be ``localhost'', the port 9102, and
183 the ``Remote'' checkbox will be ticked.\par
184 See below for more information on this mode of operation. % TODO: Link
185 \end{benumerate}
186 \item[Timeout] is used to set the connection timeout so the Tray Monitor will
187 not try infinitely long to connect to the counterpart.\par
188 This is a typical \bacula{} ``time-string'', so the input format can be pretty
189 flexible. However, for the purpose of network timeouts, plain integers
190 representing numbers are suitable, and values between 5 and 300 (seconds)
191 should be reasonable. The default unit is seconds.
192 \item[Monitor] is a checkbox which, when selected, tells the Tray Monitor
193 program that the currently configured daemon should update the
194 tray icon. When the daemon has some activity the tray icon will indicate
195 this. Otherwise the tray icon will show an idle state.\par
196 This setting is most useful on client systems where it can give an
197 indication of current activity to the desktop user, so that disrupting
198 \bacula{} operations by shutting down or disconnecting from the network can
199 be avoided.
200 \end{bdescription}
201
202 \subsubsection{Client configuration}
203
204 In most cases, the \bacula{} File Daemon will be the one running on the local
205 machine. In addition, a Client can also serve as a proxy for the Tray Monitor
206 program to connect to a Director. This additional functionality is enabled with
207 a configuration item:
208
209 \begin{bdescription}
210 \item[Remote] tells the Tray Monitor that this client can be used as a
211 proxy to connect to a Director. This operation mode allows to initiate
212 connections between Director and File Daemon from the client side, which is
213 invaluable in situations where the DIR cannot (reliably) contact the
214 File Daemon. Such a client-initiated connections can then be used to run
215 jobs on clients inaccessible by the Director.
216 See~\vref{blb:ch:ui-traymon:proxyconn} for more details.
217 \end{bdescription}
218
219
220 \subsubsection{Director Configuration}
221
222 In addition to the common configuration settings described above, one
223 additional parameter is available here:
224
225 \begin{bdescription}
226 \item[Use SetIp] causes the Tray Monitor program to send a \texttt{setip}
227 command to the Director, which will enable the Director to communicate with
228 this client.
229
230 This setting can be useful in cases where the client computer has no fixed
231 \acs{IP} address or \acs{DNS} name, but can be reached directly by the Director. Once the
232 \bcommandname{setip} command was executed, the Director can use regular ways to
233 operate on this client, for example starting scheduled Jobs or querying the
234 Client status.
235
236 For the \bcommandname{setip} command to succeed, it is required to use
237 exactly identical Client and Console resource names in the Director's
238 configuration. The Main manual describes this feature in detail.
239 %TODO: link to proper location when integrated into main manual
240 %NOTE: I don't like to repeat the explanation here -- duplicating
241 % information is to be avoided as much as possible to keep the whole
242 % set of manuals maintainable. I admit that we need better structure
243 % and easier linking between documentation parts... ARL
244 %% partial ANSWER: with the macros defined for the current doc building process, it is kind of easy to link or reference at least any part of the documentation
245 %% to another one. Would it include the whitepapers means there are more work to do.
246 %% Another thing is that maybe we should consider moving to a real documentation system (Red Hat is IMHO a very good example). Philippe - 28-sept-2018
247 \end{bdescription}
248
249
250 \subsubsection{Configuration file structure}
251
252 As usual for \bacula{} components, the configuration for the Tray Monitor program
253 is stored as a plain text file; the format is exactly the same as used with
254 all the other components.
255
256 When you configure \bacula{} Tray Monitor with the \acs{GUI}, a certain knowledge
257 of the \bacula{} configuration scheme is surely helpful. When you edit the file
258 with a text editor, this knowledge becomes essential.
259
260 However, there is a rather simple mapping from fields in the \acs{GUI} to
261 configuration file contents: Each tab represents a resource of the specified
262 type, and each actual setting is named identical or similarly in both the \acs{GUI}
263 and the file. For example, the following configuration file
264 \begin{bVerbatim}
265 Monitor {
266 Name="wgb-sql14b-con"
267 Refresh Interval = 1001
268 Display Advanced Options = yes
269 }
270 Client {
271 Name = "wgb-sql14b-fd"
272 Address = "localhost"
273 Password = "85test-onremote"
274 Port = 9102
275 Connect Timeout = 10
276 Remote = yes
277 Monitor = yes
278 }
279 \end{bVerbatim}
280 exactly represents the settings in the \acs{GUI} as seen in figure~\vref{blb:fig:tray-monitor-conf-mon-cli}.
281
282 \bimageH[11.7cm]{tray-monitor-conf-mon-cli}{Tray Monitor Configuration as seen in Listing}{blb:fig:tray-monitor-conf-mon-cli}
283
284 \subsubsection{Default locations of configuration files}
285
286 The default locations of user specific configuration files that are written by
287 the GUI are \bfilename{/home/username/.bacula-tray-monitor.conf} (Linux) and
288 \bfilename{C:\Users\username\AppData\Roaming\bacula-tray-monitor.conf} (Windows,
289 note that AppData is a hidden directory).
290
291 \subsection{Monitoring}
292 \bimageH[8.91cm]{tray-monitor-mon-cli}{Tray Monitor Client Display}{blb:fig:tray-monitor-mon-cli}
293
294 After double-clicking the Tray Monitor icon, or when selecting the
295 ``Display\ldots{}'' item in its context menu, the monitor screen is shown. In this
296 screen, a tab selects which of the configured components of \bacula{} to show.
297
298 The monitoring panel consists of three areas, well known to any \bacula{}
299 administrator, but probably not so easily understood by users without
300 prior \bacula{} knowledge. On top, the general daemon status is shown. This gives
301 information about the identity of the component, in particular the configured
302 name, the version of the software, which plugins are currently loaded, and when
303 the service process was started. In addition, some global settings may be shown
304 -- for a File Daemon, this is the configured Bandwidth Limit. Note that
305 in-depth diagnostic information as presented by the \btool{bconsole}
306 \bcommandname{status} command is \textbf{not} shown.
307 \medskip
308
309 Below the general status a list shows all currently running jobs. This list
310 contains the JobID and the job's name, and as seen in
311 figure~\vref{blb:fig:tray-monitor-mon-cli}, with the number of files and the amount
312 of data already processed also gives some indication of job progress. The Error
313 counter column, while looking important, is much less so than it appears,
314 since actual error causes or messages can not be seen here.
315 \medskip
316
317 Finally, the lowermost part of the monitoring panel shows an overview of the
318 last jobs run by the particular daemon. Status text field is color coded (e.g.
319 green for successful jobs).
320 \bigskip
321
322 Note that column headers can be clicked to change the sort order of the table,
323 and column widths can be modified by dragging the table header column
324 separators.
325 \bigskip
326
327 In the bottom right corner of the monitoring panel there is an icon to
328 immediately refresh the display, while outside of the monitoring panel and the
329 tab view, in the bottom left corner of the display window, the automatic
330 refresh interval can be adjusted.
331
332 The ``Close'' button at the bottom right corner will close the display window
333 in the same way as a click on the window decoration close button does.
334
335
336 \subsection{Running Jobs}
337 You can start a job by selecting ``Run\ldots{}'' from the context menu of the
338 tray icon.
339
340 If more than one Director or Clients with ``Remote'' capability are configured,
341 a window will be shown to select the Director to use for the Job to be run.
342 This window will appear as shown in
343 figure~\vref{blb:fig:tray-monitor-run-dirselect}. The name used in the selection
344 drop-down menu is the one configured in the ``Name:'' setting of the component,
345 see above in the ``Configuration'' section.
346
347 \bimageH[2.38cm]{tray-monitor-run-dirselect}{Selecting a Director to run a Job}{blb:fig:tray-monitor-run-dirselect}
348
349 The ``Run Job'' window will be shown, which presents Job properties
350 and an estimate of how much data will be backed up. The estimate will be
351 updated when Job properties are changed. Be aware that this estimate is
352 not based on current backup source information, i.\,e. it is not the
353 result that you would get with the \bcommandname{estimate} command, but it is
354 derived using a simple regression from Catalog information.
355 The information presented is, however, usually enough to determine if
356 the Job can finish during the remaining working hours.
357 \medskip
358
359 Depending on the general Monitor configuration setting to ``Display Advanced Options'',
360 a second, tabbed panel will be available and
361 allow to change many other Job parameters, such as the backup level,
362 the File Set to use, or the backup target like Pool and Storage device.
363 \medskip
364
365 All settings are subject to access control restrictions configured at
366 the Director, thus it is possible to have specific and secure options
367 per each user (with each user connecting to their ``own'' access
368 controlled Console resource).
369 %TODO: Point to relevant main manual chapter, or - better - a
370 % streamlined document describing \acsp{ACL}
371
372 \subsection{Local Scheduling -- the Command Directory}
373 \label{blb:TrayMonitorCommandDirectoryChapter}
374 The Tray Monitor configuration item \texttt{Command Directory} can be used to
375 automate \bacula{} activities through the Tray Monitor itself. In particular it
376 allows to schedule jobs on the client machine, and not (only) inside the
377 Director's configuration.
378
379 If configured with a path readable by the Tray Monitor program, the
380 Tray Monitor, while running, will regularly look for files ending on
381 \bfilename{".bcmd"} and process them. Once a file was processed, it will
382 be renamed to end with \bfilename{.bcmd.ok}. These command files need to
383 follow a specific syntax:
384
385 \begin{bVerbatim}
386 component-name: bconsole-command
387 \end{bVerbatim}
388
389 \texttt{component-name} must be one of the defined Director or Client
390 resources (Client only with \bvalueddirective{Remote}{Yes}).
391
392 \texttt{bconsole-command} is just a plain \bconsolename{} command which
393 will be sent to the Director (possibly through the File Daemon).
394
395 The most useful command here is \bcommandname{run job=job-name} to initiate backups,
396 where \texttt{job-name} would be the one that backs up from the local machine.
397 \bigskip
398
399 The solution to schedule backups of the local machine is accordingly
400 to have \btool{cron} or Windows' Task Scheduler create appropriate
401 command files in the right location.
402
403 Part of that scheduled task could be to verify connectivity to the
404 Director. An example suitable on a Linux or Unix system might look like
405 this:
406
407 \begin{bVerbatim}
408 #!/bin/sh
409 if ping -c 1 director &> /dev/null
410 then
411 echo "my-dir: run job=backup" > /path/to/commands/backup.bcmd
412 fi
413 \end{bVerbatim}
414
415 On a Windows system, a batch script like the following could be used:
416
417 \begin{bVerbatim}
418 @ECHO OFF
419 ping -n 1 -4 lsb-236.lsb.os.baculasystems.com >nul:
420 if ERRORLEVEL 1 (
421 echo Director not reachable!
422 ) else (
423 echo wgb-sql14b-fd: run job=wgb-sql14b-all>%LOCALAPPDATA%\Bacula\commands\runnow.bcmd
424 )
425 \end{bVerbatim}
426
427 Using \btool{cron} to start this sort of script is pretty simple for
428 a user with some Linux or Unix knowledge. Unfortunately, creating a
429 scheduled task on a Windows machine is somewhat difficult to explain
430 due to the number of required mouse clicks. We may provide step-by-step
431 instructions at a later time.
432
433
434 \subsection{Proxied Connection}
435 \label{blb:ch:ui-traymon:proxyconn}
436 With the Tray Monitor program providing a user friendly interface,
437 and support for local scheduling, there's only one element missing
438 to enable \bacula{} backing up computers that are unreliably available
439 and may not be accessible from the Director itself: A way to enable the
440 Director to run a Job on a given client, even if, from the Director,
441 the client can not be accessed.
442
443 For many desktop and most laptop users, \bacula{} until now was not a
444 very convenient solution, because it relied on the Director being
445 configured with the client computer's \acs{IP} address or host name, and
446 then the Director being able to connect to the client.
447
448 In many corporate networks, however, there is neither \acs{DNS} resolution nor
449 static \acs{IP} addressing in place for desktop computers. Furthermore, if
450 the client computer is connected outside of the organization's \acs{LAN},
451 for example in a home office behind a \acs{NAT}'ing router, there will be no
452 reliable way to connect to it at all.
453
454 In those situations, it is essential that the File Daemon connects to the
455 Director, and the Director then uses this \acs{TCP} connection to control the
456 backup Job.
457
458 This is possible as of version~8.6 of \bee{}
459 %TODO: and version 7.? of the community edition
460 using the \textit{Client-Initiated Connection} feature. Note that both
461 Director and File Daemon need to support this functionality.
462
463 As we assume that such a setup of \bacula{} will usually be implemented to
464 back up user computers, we will provide the documentation including
465 a restricted console using \acsp{ACL}.
466 \bigskip
467
468 We will first provide a description of the connection flow for a job
469 that makes use of the proxied console connection, and then describe
470 the required configuration in detail.
471
472 \subsubsection{Connection Flow}
473 For a Client-Initiated Backup to work through an FD-initiated connection,
474 the following sequence of events will happen:
475 \begin{benumerate}
476 \item Console wants to start a Job, either manually or automated.\\
477 The Director to run this job on should be the local FD, and, if the
478 Tray Monitor is used, it should be configured with
479 \texttt{Remote = Yes}.
480 \item The Console (most likely, the Tray Monitor program) connects to the
481 local FD.\\
482 Inside the FD configuration, such incoming connections are represented
483 as a Director resource with two new settings: \texttt{Remote} and
484 \texttt{Console}.
485 \item The Console submits the \texttt{proxy} command to the FD.\\
486 Following this, the FD will use the Console resource referenced by the
487 Director resource the current Console connection uses and use the
488 provided information (Address, Name, and Password) to try to establish
489 a connection to the ``real'' Director. If that succeeds, all further
490 incoming console commands are directly passed on to that Director.
491 \item The Console submits the backup Job \bcommandname{run} command with the
492 new option \texttt{fdcalled=1}.
493 \item The Director checks against \acsp{ACL} configured inside its Console
494 resource representing the current connection if the Job is allowed,
495 and if it is, it first marks the existing connection from the FD as
496 related to this Job, and then runs the Job.
497 \item When the DIR starts using the established connection for
498 a Job, the FD closes the connection to the incoming console; the connection
499 to the DIR is used exclusively for Job-related communication, and
500 thus a console connected to it could not be used for anything useful
501 from this moment on.
502 \item The Director, following its regular mode of operation, eventually
503 sends a command to the FD telling it which Storage Daemon to contact
504 for data transfers.
505 \item The File Daemon then connects to the SD as usual.
506 \item The Backup Job progresses as usual, and at the end, the FD will
507 report the final Job status to the DIR.
508 \item Eventually, the \acs{TCP} connection between FD and DIR will be properly
509 shutdown.
510 \end{benumerate}
511
512 The above step-by-step description already indicates where specific
513 configuration for this operational mode is required:
514 \begin{bitemize}
515 \item The console program (either \btool{bconsole} or the \btool{Tray Monitor})
516 needs to be configured to connect to a File Daemon (usually
517 the one running locally) instead of directly to a DIR.
518 \item The File Daemon used needs to be configured with at least one
519 additional Director resource with specific settings, one of them
520 being the reference to a \bresourcename{Console} resource.
521 \item In the Director's configuration, a client-specifc \bConsole{}
522 resource should be used, and this should be restricted in capabilities
523 as far as possible.
524 \item A Job that has to use a FD-initiated connection needs to be
525 started with a specific new option, namely \texttt{fdcalled=1}.
526 \end{bitemize}
527
528 For an experienced \bacula{} administrator, having to add \bConsole{} and more
529 \bDirector{} resources to a File Daemon configuration will be unexpected.
530 For new \bacula{} administrators, the complexity of the configuration scheme
531 (which, as usual, is a result of the built-in flexibility) may be
532 intimidating.
533
534 For this reason, we provide an overview of the required configuration
535 in figure~\vref{blb:fig:tray-monitor-and-related-conf-overview}.
536
537 \bimageH[\linewidth,angle=90]{cib-overview}{Configuration overview: resources and their relationships}{blb:fig:tray-monitor-and-related-conf-overview}
538 %% \begin{figure}[p]
539 %% \includegraphics[angle=90,keepaspectratio,width=\linewidth,totalheight=19cm]{Overview}
540 %% \caption{Configuration overview: resources and their relationships}
541 %% \label{blb:fig:tray-monitor-and-related-conf-overview}
542 %% \end{figure}
543
544 In the overview figure, we have included a \bconsole{}
545 configuration which has not yet been mentioned. However, it works
546 essentially identical to the Tray Monitor program connectivity, but
547 allows -- and requires! -- the user to run arbitrary commands with all
548 possible options. At this time, this is the only way to restore
549 data using Client-Initiated connections.
550 \medskip
551
552 The figure \vref{blb:fig:tray-monitor-and-related-conf-overview} shows all needed configuration entities, in some cases
553 excerpts from the full configuration, in others the complete files.
554
555 Colored arrows indicate the relationships between resources. Most of
556 them are also relationships between daemons potentially running on
557 separate hosts, accordingly, any of those will require \acs{TCP}/\acs{IP}
558 connectivity, including routing, name resolution, firewall and
559 \acs{TCP}~Wrapper configuration. However, managing those aspects should
560 not be an additional effort for \bacula{} administrators, as no additional
561 requirements are introduced, nor will it be a problem for most users,
562 as the common desktop configurations allow outgoing connections already.
563
564 \subsubsection{Resource relationships}
565 When looking at the configuration overview in
566 figure~\vref{blb:fig:tray-monitor-and-related-conf-overview}, it is easy
567 to spot distinct relationships. We will discuss them, starting at the
568 console program used.
569
570 \paragraph{Console} programs intended to use a proxied connection to
571 the Director, or intended to start a Job through a client-initiated
572 connection, need to be configured to contact the File Daemon used to
573 serve as proxy to the Director, not the Director itself. Thus, the
574 configuration will (usually) use \bdirectivename{Address = localhost} and a
575 port number of \bvalue{9102}.
576
577 Note that \btool{bconsole} is essentially agnostic of the fact that
578 it connects to a File Daemon, not a Director, and thus uses a
579 Director configuration resource, while the Tray Monitor program does
580 know about those features and accordingly uses a slightly different
581 configuration scheme with a Client resource with \bdirectivename{Remote = Yes}
582 set.
583
584 Also, \btool{bconsole} and the Tray Monitor program use different
585 resources to define themselves (which is where the name used for
586 authentication is taken from), so there will be different ``Identity''
587 resources in use. It is possible and may be reasonable to use the
588 same name and password, though, as the File Daemon can use the same
589 resource to configure the properties of the connecting agent.
590 \medskip
591
592 In figure~\vref{blb:fig:tray-monitor-and-related-conf-overview}, the
593 relationship between Tray Monitor and (local) File Daemon configuration
594 resources is shown in green, and the relationship from a
595 \btool{bconsole} configuration to that of the File Daemon is shown in
596 orange.
597
598 \paragraph{File Daemon} configuration for proxied connections to a
599 Director are a bit more complex.
600
601 First, the File Daemon needs to accept incoming user agent connections
602 from \btool{bconsole} or the Tray Monitor program. However, these
603 connections will (potentially) not only be used to query the FD's
604 status, but also to submit more powerful commands, so a Monitor resource
605 is not suitable.
606
607 Instead, the File Daemon has essentially to act as a Director for the
608 user agent, so this functionality is configured in a \bDirector{} resource.
609
610 This is essentially just a ``normal'' \bDirector{} resource, but it is
611 advisable to have distinct ones for ``real'' \bacula{} Directors as needed
612 (usually there will only be one ``real'' Director) and for incoming user agents (also, there
613 will usually be exactly one of them).
614
615 This is because direct Director connections may still be required in
616 some cases, and it is surely advisable to have different passwords
617 for a Director and for a user agent. Also, it is much easier to
618 understand log files if different names are used for real Directors and
619 user agent connections.
620
621 To enable the proxy functionality of the File Daemon, the directive
622 \bdirectivename{Remote} needs to be set to \bvalue{yes} for those \bDirector{}
623 resources representing incoming user agent connections.
624
625 In addition, a \bdirectivename{Console} directive should be present and indicate
626 a \bConsole{} resource used to contact the ``real'' Director -- see below
627 for details.
628
629 If no Console is referenced, the File Daemon will automatically select
630 a Console it finds in its configuration, but since it is possible to have
631 several of them defined, each with different properties, it is much
632 safer and more clearly understandable what is configured if an explicit
633 Console reference is used.
634
635 In the overview in figure~\vref{blb:fig:tray-monitor-and-related-conf-overview}, this Console reference is indicated in blue.
636 \bigskip
637
638 The Console resource of the File Daemon specifies connection
639 information and credentials to contact a ``real'' Director as usual.
640
641 It is advisable to use distinct names and passwords for each such
642 Director connection, so that access can be controlled at least with the
643 granularity of client machines.
644
645 However, if different users on a given machine will be using proxied
646 connections to one or more Directors, there should be distinct Director
647 resources per user, each using its own set of credentials.
648
649 As the File Daemon configuration file should be protected against user
650 access, this allows separating user permissions and will allow to
651 distinguish activity logged.
652
653 However, the local machine administrator will always be able to read
654 all user credentials, thus needs to be trustworthy to at least the
655 extent all the users combined are trusted.
656
657 Additional considerations apply to logging of
658 File Daemon activity. Usually all File Daemon activity is logged to a
659 default Director (Job-related activity is always logged to the initiating
660 Director). However, in environments making use of the Client-Initiated
661 Connection facilities, the central Director may not be a suitable target
662 for the File Daemon messages as it will be inaccessible most of the
663 time.
664
665 Thus we recommend to configure the File Daemon to write its messages to
666 a local log file or logging daemon.
667
668 \paragraph{Director} configuration for use in an environment using
669 Client-Initiated Connections relies heavily on the use of Named Consoles
670 with \acsp{ACL}. In the configuration overview of
671 figure~\vref{blb:fig:tray-monitor-and-related-conf-overview}, we show one
672 such Console resource and red arrows from the File Daemon's \bConsole{}
673 resource indicate how it is referenced from the (proxying) File Daemon.
674
675 We also show the ``regular'' configuration, with the File Daemon being
676 contacted by the Director (the Director-side Client resource is not
677 in the overview) with a faint red arrow. The important part here is that
678 authentication information is not shared between the two different
679 connection direction setups.
680
681 \subparagraph{Access Control Lists} should be in place in the
682 Director-side configuration for all Console resources that are
683 used by non-administrative users. Only \bacula{} instance administrators
684 should ever have full access to a Director.
685
686 Using the configuration scheme outlined, it is easily possible to have
687 per-user Console configurations, typically restricting access to only
688 the required resources. Most of the time, for example, there will
689 be only one client and one backup Job allowed for such a Console
690 connection.
691
692 In the overview graph we present a simplified, not very closely
693 restricted Console resource.
694
695 In practice, much more restrictive configurations will be applied.
696 We trust that a \bacula{} administrator will know which commands their users
697 are supposed to execute, and which resources they need to access.
698 However, with the Tray Monitor program, it may not be obvious which
699 commands in particular are required, thus we provide the full list
700 of mandatory commands here. Note that resource (for example, Job, Pool
701 and Storage) restrictions need to be added.
702
703 A typical \bdirectivename{Command ACL} directive for a Console used by a
704 Tray Monitor which is allowed to run Jobs will look require to
705 have at least the following contents:
706 \begin{bVerbatim}
707 CommandACL = status, .estimate, .clients, .jobs, .pools, .storage, .filesets, run
708 \end{bVerbatim}
709
710
711 \subsubsection{Using \btool{bconsole} for User-Initiated Jobs}
712 Besides using the Tray Monitor utility to monitor and control a
713 Director, it is also possible to use the console program
714 \btool{bconsole} with the File Daemon as a proxy, including the
715 ability to start jobs which can use the File Daemon-initiated Director
716 connection.
717
718 At the current time, this is actually the only reliable way to
719 enable users with a restricted console connection and without full
720 access from the Director to their desktop to restore from their backups.
721
722 To use these facilities, three items are important:
723 \begin{benumerate}
724 \item The programs involved need to be configured accordingly, i.\,e. as
725 outlined above.
726 \item To initiate the proxied connection through the File Daemon,
727 before any command intended for the Director is entered, the command
728 \texttt{proxy} needs to be submitted. It should return with an ``Ok''
729 message.
730 \item Any job started that should use the established console
731 connection to the Director needs the additional parameter
732 \texttt{fdcalled=1} in its command line.
733 \end{benumerate}
734
735 Note that the extra command and parameter are not required when
736 submitting commands through the Tray Monitor program's command file
737 facility. Also note that once a job has started, the console
738 connection between File Daemon and \btool{bconsole} will be terminated,
739 causing \btool{bconsole} to end. Job status can be observed with a new
740 \btool{bconsole} invocation; in fact, the status of the local File
741 Daemon can then be observed without going through the Director. An example session is shown in figure~\vref{blb:fig:bconsole-fd-pcc-session}.
742
743 \bimageH[7.5cm]{bconsole-fd-pcc-session}{Remote, Proxied \texttt{bconsole} Session with Job Run}{blb:fig:bconsole-fd-pcc-session}
744
745 %%\subsubsection{Configuration File}
746
747 \subsection{Monitoring}
748
749 \subsection{Running Jobs}
750
751 \subsection{Proxied Connection}
752
753
754 \subsection{Supported Platforms}
755 The Tray Monitor program is available for the following platforms:
756 \begin{bitemize}
757 \item Microsoft Windows, both 32 and 64 bit, on all Windows versions still
758 under vendor support. % no, we will not answer questions re Server 2k3 or XP
759 \item Linux:
760 \begin{bitemize}
761 % TODO: Complete the list: distros, versions, desktops
762 \item Ubuntu: 14.04, x86 and x86-64, with XFCE desktop
763 \item Red Hat Enterprise Linux and clones like CentOS: 6.x, 7.x,
764 x86 and x86-64, with XFCE desktop
765 \end{bitemize}
766 %\item Mac OS X %%%TODO: verify
767
768 \subsection{Command Line Options}
769 The Tray Monitor program accepts the following command line options and
770 parameters:
771 \begin{bdescription}
772 \item[-c \bbracket{filename}] Configuration file to use. If the file does not exist,
773 the program starts with an empty configuration and shows the configuration
774 panel.
775 \item [-d \bbracket{number}] Debug level. The higher the number, the more information
776 is displayed.
777 \item [-dt] Print timestamps in debug output.
778 \item[-t] Test the configuration and exit. No output is a good sign.
779 \item[-W \bzeroone{}] Force detection of systray capability. A zero indicates to
780 run without tray icon, a one forces to use tray capability even if not
781 detected.
782 \item [-?] Display short help and exit.
783 \end{bdescription}
784 \end{bitemize}