/usr/share/doc/exim4-doc-html/spec_html/ch-the_exim_monitor.html is in exim4-doc-html 4.90.1-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 | <!DOCTYPE html PUBLIC "XSLT-compat">
<html lang="en-GB">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<link rel="stylesheet" type="text/css" href="common.css">
<meta name="author" content="The Exim Project. <https://www.exim.org/>">
<meta name="copyright" content="Copyright ©1995-2012 The Exim Project. All rights reserved">
<meta name="description" content="Exim is a message transfer agent (MTA) developed at the University of Cambridge for use on Unix systems connected to the Internet.">
<meta name="keywords" content="exim,smtp,mta,email">
<meta name="robots" content="noodp,noydir,index,follow">
<meta name="viewport" content="width=device-width">
<title>54. The Exim monitor</title>
<link rel="stylesheet" type="text/css" href="chapter.css">
<link rel="canonical" href="https://www.exim.org/exim-html-current/doc/html/spec_html/ch-the_exim_monitor.html">
</head>
<body class="no-js">
<script type="text/javascript">document.body.className=(' '+document.body.className+' ').replace('no-js','with-js');</script><h1 id="header"><a href="http://www.exim.org">Exim Internet Mailer</a></h1>
<div id="outer">
<ul id="nav_flow" class="nav">
<li><a href="https://www.exim.org/index.html">Home</a></li>
<li><a href="https://www.exim.org/mirrors.html">Download</a></li>
<li><a href="https://www.exim.org/docs.html">Documentation</a></li>
<li><a href="https://www.exim.org/maillist.html">Mailing Lists</a></li>
<li><a href="http://wiki.exim.org/">Wiki</a></li>
<li><a href="https://bugs.exim.org/">Bugs</a></li>
<li><a href="https://www.exim.org/static/doc/security">Security</a></li>
<li><a href="https://www.exim.org/credits.html">Credits</a></li>
<li class="search"><form action="https://encrypted.google.com/search" method="get">
<span class="search_field_container"><input type="search" name="q" placeholder="Search Docs Online" class="search_field"></span><input type="hidden" name="hl" value="en"><input type="hidden" name="ie" value="UTF-8"><input type="hidden" name="as_qdr" value="all"><input type="hidden" name="q" value="site:www.exim.org"><input type="hidden" name="q" value="inurl:exim-html-current">
</form></li>
</ul>
<div id="inner"><div id="content">
<a class="previous_page" href="ch-exim_utilities.html"><-previous</a><a class="next_page" href="ch-security_considerations.html">next-></a><div id="chapter" class="chapter">
<h2 id="CHAPeximon" class=""><a href="ch-the_exim_monitor.html">Chapter 54 - The Exim monitor</a></h2>
<p>
The Exim monitor is an application which displays in an X window information
about the state of Exim’s queue and what Exim is doing. An admin user can
perform certain operations on messages from this GUI interface; however all
such facilities are also available from the command line, and indeed, the
monitor itself makes use of the command line to perform any actions requested.
</p>
<div class="section">
<h3 id="SECID264" class="">1. Running the monitor</h3>
<p>
The monitor is started by running the script called <span class="docbook_emphasis">eximon</span>. This is a shell
script that sets up a number of environment variables, and then runs the
binary called <span class="docbook_filename">eximon.bin</span>. The default appearance of the monitor window can
be changed by editing the <span class="docbook_filename">Local/eximon.conf</span> file created by editing
<span class="docbook_filename">exim_monitor/EDITME</span>. Comments in that file describe what the various
parameters are for.
</p>
<p>
The parameters that get built into the <span class="docbook_emphasis">eximon</span> script can be overridden for
a particular invocation by setting up environment variables of the same names,
preceded by <code class="docbook_literal">EXIMON_</code>. For example, a shell command such as
</p>
<div class="docbook_literallayout"><pre>
EXIMON_LOG_DEPTH=400 eximon
</pre></div>
<p>
(in a Bourne-compatible shell) runs <span class="docbook_emphasis">eximon</span> with an overriding setting of
the LOG_DEPTH parameter. If EXIMON_LOG_FILE_PATH is set in the environment, it
overrides the Exim log file configuration. This makes it possible to have
<span class="docbook_emphasis">eximon</span> tailing log data that is written to syslog, provided that MAIL.INFO
syslog messages are routed to a file on the local host.
</p>
<p>
X resources can be used to change the appearance of the window in the normal
way. For example, a resource setting of the form
</p>
<div class="docbook_literallayout"><pre>
Eximon*background: gray94
</pre></div>
<p>
changes the colour of the background to light grey rather than white. The
stripcharts are drawn with both the data lines and the reference lines in
black. This means that the reference lines are not visible when on top of the
data. However, their colour can be changed by setting a resource called
“highlight” (an odd name, but that’s what the Athena stripchart widget uses).
For example, if your X server is running Unix, you could set up lighter
reference lines in the stripcharts by obeying
</p>
<div class="docbook_literallayout"><pre>
xrdb -merge <<End
Eximon*highlight: gray
End
</pre></div>
<p>
In order to see the contents of messages on the queue, and to operate on them,
<span class="docbook_emphasis">eximon</span> must either be run as root or by an admin user.
</p>
<p>
The command-line parameters of <span class="docbook_emphasis">eximon</span> are passed to <span class="docbook_filename">eximon.bin</span> and may
contain X11 resource parameters interpreted by the X11 library. In addition,
if the first parameter starts with the string "gdb" then it is removed and the
binary is invoked under gdb (the parameter is used as the gdb command-name, so
versioned variants of gdb can be invoked).
</p>
<p>
The monitor’s window is divided into three parts. The first contains one or
more stripcharts and two action buttons, the second contains a “tail” of the
main log file, and the third is a display of the queue of messages awaiting
delivery, with two more action buttons. The following sections describe these
different parts of the display.
</p>
</div>
<div class="section">
<h3 id="SECID265" class="">2. The stripcharts</h3>
<p>
The first stripchart is always a count of messages on the queue. Its name can
be configured by setting QUEUE_STRIPCHART_NAME in the
<span class="docbook_filename">Local/eximon.conf</span> file. The remaining stripcharts are defined in the
configuration script by regular expression matches on log file entries, making
it possible to display, for example, counts of messages delivered to certain
hosts or using certain transports. The supplied defaults display counts of
received and delivered messages, and of local and SMTP deliveries. The default
period between stripchart updates is one minute; this can be adjusted by a
parameter in the <span class="docbook_filename">Local/eximon.conf</span> file.
</p>
<p>
The stripchart displays rescale themselves automatically as the value they are
displaying changes. There are always 10 horizontal lines in each chart; the
title string indicates the value of each division when it is greater than one.
For example, “x2” means that each division represents a value of 2.
</p>
<p>
It is also possible to have a stripchart which shows the percentage fullness of
a particular disk partition, which is useful when local deliveries are confined
to a single partition.
</p>
<p>
This relies on the availability of the <span class="docbook_function">statvfs()</span> function or equivalent in
the operating system. Most, but not all versions of Unix that support Exim have
this. For this particular stripchart, the top of the chart always represents
100%, and the scale is given as “x10%”. This chart is configured by setting
SIZE_STRIPCHART and (optionally) SIZE_STRIPCHART_NAME in the
<span class="docbook_filename">Local/eximon.conf</span> file.
</p>
</div>
<div class="section">
<h3 id="SECID266" class="">3. Main action buttons</h3>
<p>
Below the stripcharts there is an action button for quitting the monitor. Next
to this is another button marked “Size”. They are placed here so that
shrinking the window to its default minimum size leaves just the queue count
stripchart and these two buttons visible. Pressing the “Size” button causes
the window to expand to its maximum size, unless it is already at the maximum,
in which case it is reduced to its minimum.
</p>
<p>
When expanding to the maximum, if the window cannot be fully seen where it
currently is, it is moved back to where it was the last time it was at full
size. When it is expanding from its minimum size, the old position is
remembered, and next time it is reduced to the minimum it is moved back there.
</p>
<p>
The idea is that you can keep a reduced window just showing one or two
stripcharts at a convenient place on your screen, easily expand it to show
the full window when required, and just as easily put it back to what it was.
The idea is copied from what the <span class="docbook_emphasis">twm</span> window manager does for its
<span class="docbook_emphasis">f.fullzoom</span> action. The minimum size of the window can be changed by setting
the MIN_HEIGHT and MIN_WIDTH values in <span class="docbook_filename">Local/eximon.conf</span>.
</p>
<p>
Normally, the monitor starts up with the window at its full size, but it can be
built so that it starts up with the window at its smallest size, by setting
START_SMALL=yes in <span class="docbook_filename">Local/eximon.conf</span>.
</p>
</div>
<div class="section">
<h3 id="SECID267" class="">4. The log display</h3>
<p>
The second section of the window is an area in which a display of the tail of
the main log is maintained.
To save space on the screen, the timestamp on each log line is shortened by
removing the date and, if <span class="docbook_option">log_timezone</span> is set, the timezone.
The log tail is not available when the only destination for logging data is
syslog, unless the syslog lines are routed to a local file whose name is passed
to <span class="docbook_emphasis">eximon</span> via the EXIMON_LOG_FILE_PATH environment variable.
</p>
<p>
The log sub-window has a scroll bar at its lefthand side which can be used to
move back to look at earlier text, and the up and down arrow keys also have a
scrolling effect. The amount of log that is kept depends on the setting of
LOG_BUFFER in <span class="docbook_filename">Local/eximon.conf</span>, which specifies the amount of memory
to use. When this is full, the earlier 50% of data is discarded – this is
much more efficient than throwing it away line by line. The sub-window also has
a horizontal scroll bar for accessing the ends of long log lines. This is the
only means of horizontal scrolling; the right and left arrow keys are not
available. Text can be cut from this part of the window using the mouse in the
normal way. The size of this subwindow is controlled by parameters in the
configuration file <span class="docbook_filename">Local/eximon.conf</span>.
</p>
<p>
Searches of the text in the log window can be carried out by means of the ^R
and ^S keystrokes, which default to a reverse and a forward search,
respectively. The search covers only the text that is displayed in the window.
It cannot go further back up the log.
</p>
<p>
The point from which the search starts is indicated by a caret marker. This is
normally at the end of the text in the window, but can be positioned explicitly
by pointing and clicking with the left mouse button, and is moved automatically
by a successful search. If new text arrives in the window when it is scrolled
back, the caret remains where it is, but if the window is not scrolled back,
the caret is moved to the end of the new text.
</p>
<p>
Pressing ^R or ^S pops up a window into which the search text can be typed.
There are buttons for selecting forward or reverse searching, for carrying out
the search, and for cancelling. If the “Search” button is pressed, the search
happens and the window remains so that further searches can be done. If the
“Return” key is pressed, a single search is done and the window is closed. If
^C is typed the search is cancelled.
</p>
<p>
The searching facility is implemented using the facilities of the Athena text
widget. By default this pops up a window containing both “search” and
“replace” options. In order to suppress the unwanted “replace” portion for
eximon, a modified version of the <span class="docbook_option">TextPop</span> widget is distributed with Exim.
However, the linkers in BSDI and HP-UX seem unable to handle an externally
provided version of <span class="docbook_option">TextPop</span> when the remaining parts of the text widget
come from the standard libraries. The compile-time option EXIMON_TEXTPOP can be
unset to cut out the modified <span class="docbook_option">TextPop</span>, making it possible to build Eximon
on these systems, at the expense of having unwanted items in the search popup
window.
</p>
</div>
<div class="section">
<h3 id="SECID268" class="">5. The queue display</h3>
<p>
The bottom section of the monitor window contains a list of all messages that
are on the queue, which includes those currently being received or delivered,
as well as those awaiting delivery. The size of this subwindow is controlled by
parameters in the configuration file <span class="docbook_filename">Local/eximon.conf</span>, and the frequency
at which it is updated is controlled by another parameter in the same file –
the default is 5 minutes, since queue scans can be quite expensive. However,
there is an “Update” action button just above the display which can be used
to force an update of the queue display at any time.
</p>
<p>
When a host is down for some time, a lot of pending mail can build up for it,
and this can make it hard to deal with other messages on the queue. To help
with this situation there is a button next to “Update” called “Hide”. If
pressed, a dialogue box called “Hide addresses ending with” is put up. If you
type anything in here and press “Return”, the text is added to a chain of
such texts, and if every undelivered address in a message matches at least one
of the texts, the message is not displayed.
</p>
<p>
If there is an address that does not match any of the texts, all the addresses
are displayed as normal. The matching happens on the ends of addresses so, for
example, <span class="docbook_emphasis">cam.ac.uk</span> specifies all addresses in Cambridge, while
<span class="docbook_emphasis">xxx@foo.com.example</span> specifies just one specific address. When any hiding
has been set up, a button called “Unhide” is displayed. If pressed, it
cancels all hiding. Also, to ensure that hidden messages do not get forgotten,
a hide request is automatically cancelled after one hour.
</p>
<p>
While the dialogue box is displayed, you can’t press any buttons or do anything
else to the monitor window. For this reason, if you want to cut text from the
queue display to use in the dialogue box, you have to do the cutting before
pressing the “Hide” button.
</p>
<p>
The queue display contains, for each unhidden queued message, the length of
time it has been on the queue, the size of the message, the message id, the
message sender, and the first undelivered recipient, all on one line. If it is
a bounce message, the sender is shown as “<>”. If there is more than one
recipient to which the message has not yet been delivered, subsequent ones are
listed on additional lines, up to a maximum configured number, following which
an ellipsis is displayed. Recipients that have already received the message are
not shown.
</p>
<p>
If a message is frozen, an asterisk is displayed at the left-hand side.
</p>
<p>
The queue display has a vertical scroll bar, and can also be scrolled by means
of the arrow keys. Text can be cut from it using the mouse in the normal way.
The text searching facilities, as described above for the log window, are also
available, but the caret is always moved to the end of the text when the queue
display is updated.
</p>
</div>
<div class="section">
<h3 id="SECID269" class="">6. The queue menu</h3>
<p>
If the <span class="docbook_option">shift</span> key is held down and the left button is clicked when the mouse
pointer is over the text for any message, an action menu pops up, and the first
line of the queue display for the message is highlighted. This does not affect
any selected text.
</p>
<p>
If you want to use some other event for popping up the menu, you can set the
MENU_EVENT parameter in <span class="docbook_filename">Local/eximon.conf</span> to change the default, or
set EXIMON_MENU_EVENT in the environment before starting the monitor. The
value set in this parameter is a standard X event description. For example, to
run eximon using <span class="docbook_option">ctrl</span> rather than <span class="docbook_option">shift</span> you could use
</p>
<div class="docbook_literallayout"><pre>
EXIMON_MENU_EVENT='Ctrl<Btn1Down>' eximon
</pre></div>
<p>
The title of the menu is the message id, and it contains entries which act as
follows:
</p>
<ul>
<li>
<p>
<span class="docbook_emphasis">message log</span>: The contents of the message log for the message are displayed
in a new text window.
</p>
</li>
<li>
<p>
<span class="docbook_emphasis">headers</span>: Information from the spool file that contains the envelope
information and headers is displayed in a new text window. See chapter
<a href="ch-format_of_spool_files.html" title="56. Format of spool files">56</a> for a description of the format of spool files.
</p>
</li>
<li>
<p>
<span class="docbook_emphasis">body</span>: The contents of the spool file containing the body of the message are
displayed in a new text window. There is a default limit of 20,000 bytes to the
amount of data displayed. This can be changed by setting the BODY_MAX
option at compile time, or the EXIMON_BODY_MAX option at run time.
</p>
</li>
<li>
<p>
<span class="docbook_emphasis">deliver message</span>: A call to Exim is made using the <span class="docbook_option">-M</span> option to request
delivery of the message. This causes an automatic thaw if the message is
frozen. The <span class="docbook_option">-v</span> option is also set, and the output from Exim is displayed in
a new text window. The delivery is run in a separate process, to avoid holding
up the monitor while the delivery proceeds.
</p>
</li>
<li>
<p>
<span class="docbook_emphasis">freeze message</span>: A call to Exim is made using the <span class="docbook_option">-Mf</span> option to request
that the message be frozen.
</p>
</li>
<li>
<p>
<span class="docbook_emphasis">thaw message</span>: A call to Exim is made using the <span class="docbook_option">-Mt</span> option to request
that the message be thawed.
</p>
</li>
<li>
<p>
<span class="docbook_emphasis">give up on msg</span>: A call to Exim is made using the <span class="docbook_option">-Mg</span> option to request
that Exim gives up trying to deliver the message. A bounce message is generated
for any remaining undelivered addresses.
</p>
</li>
<li>
<p>
<span class="docbook_emphasis">remove message</span>: A call to Exim is made using the <span class="docbook_option">-Mrm</span> option to request
that the message be deleted from the system without generating a bounce
message.
</p>
</li>
<li>
<p>
<span class="docbook_emphasis">add recipient</span>: A dialog box is displayed into which a recipient address can
be typed. If the address is not qualified and the QUALIFY_DOMAIN parameter
is set in <span class="docbook_filename">Local/eximon.conf</span>, the address is qualified with that domain.
Otherwise it must be entered as a fully qualified address. Pressing RETURN
causes a call to Exim to be made using the <span class="docbook_option">-Mar</span> option to request that an
additional recipient be added to the message, unless the entry box is empty, in
which case no action is taken.
</p>
</li>
<li>
<p>
<span class="docbook_emphasis">mark delivered</span>: A dialog box is displayed into which a recipient address
can be typed. If the address is not qualified and the QUALIFY_DOMAIN parameter
is set in <span class="docbook_filename">Local/eximon.conf</span>, the address is qualified with that domain.
Otherwise it must be entered as a fully qualified address. Pressing RETURN
causes a call to Exim to be made using the <span class="docbook_option">-Mmd</span> option to mark the given
recipient address as already delivered, unless the entry box is empty, in which
case no action is taken.
</p>
</li>
<li>
<p>
<span class="docbook_emphasis">mark all delivered</span>: A call to Exim is made using the <span class="docbook_option">-Mmad</span> option to
mark all recipient addresses as already delivered.
</p>
</li>
<li>
<p>
<span class="docbook_emphasis">edit sender</span>: A dialog box is displayed initialized with the current
sender’s address. Pressing RETURN causes a call to Exim to be made using the
<span class="docbook_option">-Mes</span> option to replace the sender address, unless the entry box is empty,
in which case no action is taken. If you want to set an empty sender (as in
bounce messages), you must specify it as “<>”. Otherwise, if the address is
not qualified and the QUALIFY_DOMAIN parameter is set in <span class="docbook_filename">Local/eximon.conf</span>,
the address is qualified with that domain.
</p>
</li>
</ul>
<p>
When a delivery is forced, a window showing the <span class="docbook_option">-v</span> output is displayed. In
other cases when a call to Exim is made, if there is any output from Exim (in
particular, if the command fails) a window containing the command and the
output is displayed. Otherwise, the results of the action are normally apparent
from the log and queue displays. However, if you set ACTION_OUTPUT=yes in
<span class="docbook_filename">Local/eximon.conf</span>, a window showing the Exim command is always opened, even
if no output is generated.
</p>
<p>
The queue display is automatically updated for actions such as freezing and
thawing, unless ACTION_QUEUE_UPDATE=no has been set in
<span class="docbook_filename">Local/eximon.conf</span>. In this case the “Update” button has to be used to
force an update of the display after one of these actions.
</p>
<p>
In any text window that is displayed as result of a menu action, the normal
cut-and-paste facility is available, and searching can be carried out using ^R
and ^S, as described above for the log tail window.
</p>
</div>
</div>
<a class="previous_page" href="ch-exim_utilities.html"><-previous</a><a class="toc_page" href="index.html">Table of Contents</a><a class="next_page" href="ch-security_considerations.html">next-></a>
</div></div>
<div id="footer">Website design by <a href="https://www.grepular.com/">Mike Cardwell</a>.</div>
<div class="left_bar"></div>
<div class="right_bar"></div>
<div id="toc">
<ul class="hidden"></ul>
<img src="contents.png" width="16" height="155">
</div>
</div>
</body>
</html>
|