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.
The monitor is started by running the script called eximon. This is a shell script that sets up a number of environment variables, and then runs the binary called eximon.bin. The default appearance of the monitor window can be changed by editing the Local/eximon.conf file created by editing exim_monitor/EDITME. Comments in that file describe what the various parameters are for.
The parameters that get built into the eximon script can be overridden for a particular invocation by setting up environment variables of the same names, preceded by ``EXIMON_''. For example, a shell command such as
EXIMON_LOG_DEPTH=400 eximon
(in a Bourne-compatible shell) runs eximon 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 eximon tailing log data that is written to syslog, provided that MAIL.INFO syslog messages are routed to a file on the local host.
X resources can be used to change the appearance of the window in the normal way. For example, a resource setting of the form
Eximon*background: gray94
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
xrdb -merge <<End Eximon*highlight: gray End
In order to see the contents of messages on the queue, and to operate on them, eximon must either be run as root or by an admin user.
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.
The first stripchart is always a count of messages on the queue. Its name can be configured by setting QUEUE_STRIPCHART_NAME in the Local/eximon.conf 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 Local/eximon.conf file.
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.
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. This relies on the availability of the statvfs() 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 Local/eximon.conf file.
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.
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.
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 twm window manager does for its f.fullzoom action. The minimum size of the window can be changed by setting the MIN_HEIGHT and MIN_WIDTH values in Local/eximon.conf.
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 Local/eximon.conf.
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 log_timezone 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 eximon via the EXIMON_LOG_FILE_PATH environment variable.
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 Local/eximon.conf, 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 Local/eximon.conf.
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.
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.
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.
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 TextPop widget is distributed with Exim. However, the linkers in BSDI and HP-UX seem unable to handle an externally provided version of TextPop 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 TextPop, making it possible to build Eximon on these systems, at the expense of having unwanted items in the search popup window.
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 Local/eximon.conf, 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.
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.
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, cam.ac.uk specifies all addresses in Cambridge, while xxx@foo.com.example 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.
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.
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. If a message is frozen, an asterisk is displayed at the left-hand side.
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.
If the shift 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.
If you want to use some other event for popping up the menu, you can set the MENU_EVENT parameter in Local/eximon.conf 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 ctrl rather than shift you could use
EXIMON_MENU_EVENT='Ctrl<Btn1Down>' eximon
The title of the menu is the message id, and it contains entries which act as follows:
message log: The contents of the message log for the message are displayed in a new text window.
headers: Information from the spool file that contains the envelope information and headers is displayed in a new text window. See chapter 48 for a description of the format of spool files.
body: 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.
deliver message: A call to Exim is made using the -M option to request delivery of the message. This causes an automatic thaw if the message is frozen. The -v 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.
freeze message: A call to Exim is made using the -Mf option to request that the message be frozen.
thaw message: A call to Exim is made using the -Mt option to request that the message be thawed.
give up on msg: A call to Exim is made using the -Mg option to request that Exim gives up trying to deliver the message. A bounce message is generated for any remaining undelivered addresses.
remove message: A call to Exim is made using the -Mrm option to request that the message be deleted from the system without generating a bounce message.
add recipient: 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 Local/eximon.conf, 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 -Mar 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.
mark delivered: 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 Local/eximon.conf, 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 -Mmd option to mark the given recipient address as already delivered, unless the entry box is empty, in which case no action is taken.
mark all delivered: A call to Exim is made using the -Mmad option to mark all recipient addresses as already delivered.
edit sender: A dialog box is displayed initialized with the current sender's address. Pressing RETURN causes a call to Exim to be made using the -Mes 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 Local/eximon.conf, the address is qualified with that domain.
When a delivery is forced, a window showing the -v 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 Local/eximon.conf, a window showing the Exim command is always opened, even if no output is generated.
The queue display is automatically updated for actions such as freezing and thawing, unless ACTION_QUEUE_UPDATE=no has been set in Local/eximon.conf. In this case the ``Update'' button has to be used to force an update of the display after one of these actions.
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.