| 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} |