File: spec_53.html

package info (click to toggle)
exim-html 3.20-1
links: PTS
area: main
in suites: etch, etch-m68k, sarge, woody
size: 2,868 kB
ctags: 4,188
sloc: makefile: 40; sh: 19
file content (825 lines) | stat: -rw-r--r-- 27,900 bytes
<HTML>
<HEAD>
<!-- This HTML file has been created by texi2html 1.52
     from spec on 25 November 2000 -->

<TITLE>Exim Specification - 53. Exim utilities</TITLE>
</HEAD>
<body bgcolor="#FFFFFF" text="#00005A" link="#FF6600" alink="#FF9933" vlink="#990000">
Go to the <A HREF="spec_1.html">first</A>, <A HREF="spec_52.html">previous</A>, <A HREF="spec_54.html">next</A>, <A HREF="spec_59.html">last</A> section, <A HREF="spec_toc.html">table of contents</A>.
<P><HR><P>


<H1><A NAME="SEC873" HREF="spec_toc.html#TOC873">53. Exim utilities</A></H1>
<P>
<A NAME="IDX1924"></A>
A number of utility scripts and programs are supplied with Exim. Most of them
are built as part of the normal building process, but the log file analyser
is entirely free-standing.

</P>

<P>



<H2><A NAME="SEC874" HREF="spec_toc.html#TOC874">53.1 Querying Exim processes</A></H2>

<P>
<A NAME="IDX1925"></A>
<A NAME="IDX1926"></A>
<A NAME="IDX1927"></A>
The shell script called <EM>exiwhat</EM> first of all empties the
file <EM>exim-process.info</EM> in Exim's spool directory.
It then uses the <EM>ps</EM> command to find all processes running exim, and sends
each one the SIGUSR1 signal. This causes each process to write a single
line describing its current activity to the file. The script waits for one
second to allow the Exim processes to react, then copies the file to the
standard output.

</P>
<P>
Unfortunately, the <EM>ps</EM> command varies between different versions of Unix. Not
only are different options used, but the format of the output is different. For
this reason, there are some system configuration options that configure exactly
how <EM>exiwhat</EM> works. If it doesn't seem to be working for you, check the
following compile-time options:

<PRE>
EXIWHAT_PS_CMD     the command for running <EM>ps</EM>
EXIWHAT_PS_ARG     the argument for <EM>ps</EM>
EXIWHAT_EGREP_ARG  the argument for <EM>egrep</EM> to select from <EM>ps</EM> output
EXIWHAT_KILL_ARG   the argument for the <EM>kill</EM> command
</PRE>

<P>
This facility is available only in operating systems where a signal handler can
be set up such that an interrupted system call is resumed when the signal
handler has finished. An example of typical output from <EM>exiwhat</EM> is
<font color=green>

<PRE>
  164 daemon: -q1h, listening on port 25
10483 running queue: waiting for 0tAycK-0002ij-00 (10492)
10492 delivering 0tAycK-0002ij-00 to mail.ref.book [42.42.42.42]
  (editor@ref.book)
10592 handling incoming call from [245.211.243.242]
10628 accepting a local non-SMTP message
</PRE>

<P>
The first number in the output line is the process number.
</font>
The third line has been split here, in order to fit it on the page. Because
Exim processes run under a variety of uids, it is necessary to run <EM>exiwhat</EM> as
root in order to be able to send the signal to all Exim processes.

</P>



<H2><A NAME="SEC875" HREF="spec_toc.html#TOC875">53.2 Summarising the queue</A></H2>

<P>
<A NAME="IDX1928"></A>
<A NAME="IDX1929"></A>
The <EM>exiqsumm</EM> utility is a Perl script, provided in the <EM>util</EM> directory,
which reads the output of <EM>exim -bp</EM> and produces a summary of the messages
by outputting a line like the following for each domain:

<PRE>
  3   2322   74m   66m  msn.com
</PRE>

<P>
This contains the number of messages for that domain, their total volume, and
the length of time the oldest and the newest have been waiting. By default the
output is sorted on the domain name, but <EM>exiqsumm</EM> has the options -<EM>a</EM> and
-<EM>c</EM>, which cause it to be sorted by oldest message and by count of messages,
respectively.

</P>
<P>
The output of <EM>exim -bp</EM> is based on the original addresses in the message,
so no addresses generated by aliasing or forwarding are included. Consequently
this applies also to the output from <EM>exiqsumm</EM>.

</P>



<H2><A NAME="SEC876" HREF="spec_toc.html#TOC876">53.3 Extracting log information</A></H2>

<P>
<A NAME="IDX1930"></A>
<A NAME="IDX1931"></A>
The <EM>exigrep</EM> utility is a Perl script, provided in the <EM>util</EM> directory, that
extracts from one or more log files all entries relevant to any message whose
log entries contain at least one that matches a given pattern. The pattern
match is case-insensitive. Thus one can search for all mail for a given user or
a given host, for example. The usage is:

<PRE>
exigrep [-l] &#60;pattern&#62; [&#60;log file&#62;] ...
</PRE>

<P>
where the -<EM>l</EM> flag means `literal', that is, treat all characters in the
pattern as standing for themselves. Otherwise the pattern must be a Perl
regular expression. If no file names are given on the command line, the
standard input is read.

</P>
<P>
If the location of a <EM>zcat</EM> command is known from the definition of
ZCAT_COMMAND in <TT>`Local/Makefile'</TT>, <EM>exigrep</EM> automatically passes any
file whose name ends in COMPRESS_SUFFIX through <EM>zcat</EM> as it searches it.

</P>



<H2><A NAME="SEC877" HREF="spec_toc.html#TOC877">53.4 Cycling log files</A></H2>

<P>
<A NAME="IDX1932"></A>
<A NAME="IDX1933"></A>
<A NAME="IDX1934"></A>
The <EM>exicyclog</EM> script can be used to cycle <EM>mainlog</EM> and <EM>rejectlog</EM> files
that have been written to local disc. This is not necessary if only syslog is
being used. Some operating systems have their own standard scripts for log
cycling, and these can be used instead of <EM>exicyclog</EM> if preferred.

</P>
<P>
Each time <EM>exicyclog</EM> is run the files get `shuffled down' by one. If the main
log file name is <EM>mainlog</EM> (the default) then when <EM>exicyclog</EM> is run <EM>mainlog</EM>
becomes <EM>mainlog.01</EM>, the previous <EM>mainlog.01</EM> becomes <EM>mainlog.02</EM> and so on,
up to a limit which is set in the script, and which defaults to 10.

</P>
<P>
In versions of Exim prior to 1.90, <EM>exicyclog</EM> used single-digits for numbers
less than ten. This was changed to make the files list in a more natural order.
The script contains conversion code. If it finds a file called <EM>mainlog.1</EM> it
attempts to rename all files in the old form to the new form.

</P>
<P>
If no <EM>mainlog</EM> file exists, the script does nothing. Reject logs are
handled similarly. Files that `drop off' the end are deleted. All files with
numbers greater than 01 are compressed, using a compression command which is
configured
by the COMPRESS_COMMAND setting in <TT>`Local/Makefile'</TT>.

</P>
<P>
It is usual to run <EM>exicyclog</EM> daily from a <EM>crontab</EM> entry of the form

<PRE>
1 0 * * *  /opt/exim/bin/exicyclog
</PRE>

<P>
In this way, each day's log is (mostly) in a separate file. There will be some
overlap from processes that have the log open at the time of renaming.

</P>
<P>
The <EM>exicyclog</EM> script can be run as the Exim user when one is defined, because
the log files will be owned by that user in that case. Otherwise it has to be
run as root.

</P>



<H2><A NAME="SEC878" HREF="spec_toc.html#TOC878">53.5 Making DBM files</A></H2>

<P>
<A NAME="IDX1935"></A>
<A NAME="IDX1936"></A>
<A NAME="IDX1937"></A>
<A NAME="IDX1938"></A>
The <EM>exim_dbmbuild</EM> program reads an input file in the format of an alias file
(see chapter 23) and writes a DBM database using the lower-cased
alias names as keys and the remainder of the information as data. The
lower-casing can be prevented by calling the program with the -<EM>nolc</EM> option.

</P>
<P>
A terminating zero is included as part of the key string. This is expected by
the <EM>dbm</EM> lookup type. However, if the option -<EM>nozero</EM> is given,
<EM>exim_dbmbuild</EM> creates files without terminating zeroes in either the key
strings or the data strings. The <EM>dbmnz</EM> lookup type can be used with such
files.

</P>
<P>
The program requires two arguments: the name of the input file (which can be a
single hyphen to indicate the standard input), and the name of the output
database. It creates the database under a temporary name, and then renames the
file(s) if all went well.
<A NAME="IDX1939"></A>
If the native DB interface is in use (USE_DB is set in a compile-time
configuration file -- this is common in free versions of Unix) the two file
names must be different, because in this mode the Berkeley DB functions create
a single output file using exactly the name given. For example:

<PRE>
exim_dbmbuild /etc/aliases /etc/aliases.db
</PRE>

<P>
reads the system alias file and creates a DBM version of it in
<EM>/etc/aliases.db</EM>.

</P>
<P>
In systems that use the <EM>ndbm</EM> routines (mostly proprietary versions of Unix),
DBM databases consist of two files with suffixes <EM>.dir</EM> and <EM>.pag</EM>. In this
environment, the suffixes are added to the second argument of <EM>exim_dbmbuild</EM>,
so it can be the same as the first. This is also the case when the Berkeley
functions are used in compatibility mode (though this is not recommended),
because in that case it adds a <EM>.db</EM> suffix to the file name.

</P>
<P>
<font color=green>
The program outputs a warning if it encounters a duplicate key, and when it
finishes, its return code is 1 rather than zero, unless the -<EM>noduperr</EM> option
is used. By default, only the first of a set of duplicates is used -- this
makes it compatible with <EM>lsearch</EM> lookups. There is an option -<EM>lastdup</EM> which
causes it to use the data for the last duplicate instead. There is also an
option -<EM>nowarn</EM>, which stops it listing duplicate keys to <EM>stderr</EM>. For other
errors, where it doesn't actually make a new file, the return code is 2.
</font>

</P>



<H2><A NAME="SEC879" HREF="spec_toc.html#TOC879">53.6 Individual retry times</A></H2>

<P>
<A NAME="IDX1940"></A>
<A NAME="IDX1941"></A>
A utility called <EM>exinext</EM> (mostly a Perl script) provides the ability to fish
specific information out of the retry database. Given a mail domain (or a
complete address), it looks up the hosts for that domain, and outputs any retry
information. At present, the retry information is obtained by running
<EM>exim_dumpdb</EM> (see below) and post-processing the output.
For example:

<PRE>
exinext piglet@milne.fict.book
kanga.milne.fict.book:100.100.8.1 error 146: Connection refused
  first failed: 21-Feb-1996 14:57:34
  last tried:   21-Feb-1996 14:57:34
  next try at:  21-Feb-1996 15:02:34
roo.milne.fict.book:100.100.8.3 error 146: Connection refused
  first failed: 20-Jan-1996 13:12:08
  last tried:   21-Feb-1996 11:42:03
  next try at:  21-Feb-1996 19:42:03
  past final cutoff time
</PRE>

<P>
You can also give <EM>exinext</EM> a local <EM>local_part</EM>, without a domain, and it
will give any retry information for it.
Also, a message id can be given to obtain retry information pertaining to a
specific message. This exists only when an attempt to deliver a message to a
remote host suffers a message-specific error (see section 48.2).
<EM>Exinext</EM> is not particularly efficient, but then it isn't expected to be run
very often.

</P>



<H2><A NAME="SEC880" HREF="spec_toc.html#TOC880">53.7 Database maintenance</A></H2>

<P>
<A NAME="IDX1942"></A>
<A NAME="IDX1943"></A>
Three utility programs are provided for maintaining the DBM files that Exim
uses to contain its delivery hint information. Each program requires two
arguments. The first specifies the name of Exim's spool directory, and the
second is the name of the database it is to operate on. These are as
follows:

</P>

<UL>

<LI>

<EM>retry</EM>: the database of retry information

<LI>

<EM>reject</EM>: the database of information about rejected messages

<LI>

<EM>wait-&#60;<EM>transport name</EM>&#62;</EM>: databases of information about messages waiting for
remote hosts

<LI>

<EM>serialize-&#60;<EM>transport name</EM>&#62;</EM>: databases of information about current
connections to hosts which are restricted to one connection at a time

<LI>

<EM>serialize-etrn-runs</EM>: database of information about current queue runs started
by the ETRN command when <EM>smtp_etrn_serialize</EM> is set.
</UL>

<P>
<A NAME="IDX1944"></A>
The entire contents of a database are written to the standard output by the
<EM>exim_dumpdb</EM> program, which has no options or arguments other than the
spool and database names. For example, to dump the retry database:

<PRE>
exim_dumpdb /var/spool/exim retry
</PRE>

<P>
Two lines of output are produced for each entry:

<PRE>
  T:mail.ref.book:242.242.242.242 146 77 Connection refused
31-Oct-1995 12:00:12  02-Nov-1995 12:21:39  02-Nov-1995 20:21:39 *
</PRE>

<P>
The first item on the first line is the key of the record. It starts with one
of the letters D, R, or T, depending on whether it refers to a directing,
routing, or transport retry. For a local delivery, the next part is the local
address; for a remote delivery it is the name of the remote host, followed by
its failing IP address. Then there follows an error code, an additional error
code, and a textual description of the error.

</P>
<P>
The three times on the second line are the time of first failure, the time of
the last delivery attempt, and the computed time for the next attempt. The line
ends with an asterisk if the cutoff time for the last retry rule has been
exceeded.

</P>
<P>
Each output line from <EM>exim_dumpdb</EM> for the reject database consists of a date
and time, followed by the letter T or F
and a fixed point number, followed by the address that was rejected, followed
either by the name of the host that sent the bad address, if this has been
verified, or otherwise the IP address. The letter is F if only one previous
rejection of this address (from this host) has been done recently, and T if a
second has occurred, causing rejection of the MAIL command, and
subsequently rejection of the RCPT commands. The fixed point number is
zero when the last rejection was a permanent one. Otherwise it records the rate
of temporary rejections for the same address from the same host, per hour.

</P>
<P>
Each output line from <EM>exim_dumpdb</EM> for the <EM>wait-<EM>xxx</EM></EM> databases
consists of a host name followed by a list of ids for messages that are or were
waiting to be delivered to that host. If there are a very large number for any
one host, continuation records, with a sequence number added to the host name,
may be seen. The data in these records is often out of date, because a message
may be routed to several alternative hosts, and Exim makes no effort to keep
cross-references.

</P>
<P>
Each output line from <EM>exim_dumpdb</EM> for the <EM>serialize-smtp</EM> database consists
of a host name preceded by the time that Exim made a connection to that host.
Exim keeps track of connections only for those hosts or networks that have been
configured for serialization.

</P>
<P>
<A NAME="IDX1945"></A>
The <EM>exim_tidydb</EM> utility program is used to tidy up the contents of the hints
databases. If run with no options, it removes all records from a database that
are more than 30 days old. The cutoff date can be altered by means of the -<EM>t</EM>
option, which must be followed by a time. For example, to remove all records
older than a week from the retry database:

<PRE>
exim_tidydb -t 7d /var/spool/exim retry
</PRE>

<P>
<font color=green>
For the <EM>wait-<EM>xxx</EM></EM> and <EM>retry</EM> databases, the -<EM>f</EM> option can also be
used. Both these databases contain items that involve message ids. In the
former these appear as data in records keyed by host -- they were messages that
were waiting for that host -- and in the latter they are the keys for retry
information for messages that have suffered certain types of error. When -<EM>f</EM>
is used, a check is made to ensure that message ids in database records are
those of messages that are still on the queue. Message ids for messages that no
longer exist are removed from <EM>wait-<EM>xxx</EM></EM> records, and if this leaves any
records empty, they are deleted. For the <EM>retry</EM> database, -<EM>f</EM> causes the
removal of records whose keys are non-existent message ids. For other types of
database, -<EM>f</EM> has no effect.
</font>

</P>
<P>
The <EM>exim_tidydb</EM> utility outputs comments on the standard output whenever it
removes information from the database. It is suggested that it be run
periodically on all the hints databases, but at a quiet time of day, since it
requires a database to be locked (and therefore inaccessible to Exim) while it
does its work.

</P>
<P>
<A NAME="IDX1946"></A>
The <EM>exim_fixdb</EM> program is a utility for interactively modifying databases.
Its main use is for testing Exim, but it might also be occasionally useful for
getting round problems in a live system. It has no options, and its interface
is somewhat crude. On entry, it prompts for input with a right angle-bracket. A
key of a database record can then be entered, and the data for that record is
displayed.

</P>
<P>
If `d' is typed at the next prompt, the entire record is deleted. For all
except the <EM>retry</EM> database, that is the only operation that can be carried
out. For the <EM>retry</EM> database, each field is output preceded by a number, and
data for individual fields can be changed by typing the field number followed
by new data, for example:

<PRE>
&#62; 4 951102:1000
</PRE>

<P>
resets the time of the next delivery attempt. Time values are given as a
sequence of digit pairs for year, month, day, hour, and minute. Colons can be
used as optional separators.

</P>



<H2><A NAME="SEC881" HREF="spec_toc.html#TOC881">53.8 Mail statistics</A></H2>

<P>
<A NAME="IDX1947"></A>
<A NAME="IDX1948"></A>
A Perl script called <EM>eximstats</EM> is supplied in the <EM>util</EM> directory.
This has been hacked about quite a bit over time. It now gives quite a lot of
information by default, but there are options for suppressing various parts of
it. Following any options, the arguments to the script are a list of files,
which should be main log files.

</P>
<P>
<EM>Eximstats</EM> extracts information about the number and volume of messages
received from or delivered to various hosts. The information is sorted both by
message count and by volume, and the top fifty hosts in each category are
listed on the standard output. For messages delivered and received locally,
similar statistics are produced per user.

</P>
<P>
The output also includes total counts and statistics about delivery errors, and
histograms showing the number of messages received and deliveries made in each
hour of the day. A delivery with more than one address in its `envelope' (for
example, an SMTP transaction with more than one RCPT command) is counted
as a single delivery by <EM>eximstats</EM>.

</P>
<P>
Though normally more deliveries than receipts are reported (as messages may
have multiple recipients), it is possible for <EM>eximstats</EM> to report more
messages received than delivered, even though the spool is empty at the start
and end of the period in question. If an incoming message contains no valid
recipients, no deliveries are recorded for it. An error report is handled as an
entirely separate message.

</P>
<P>
<EM>Eximstats</EM> always outputs a grand total summary giving the volume and number
of messages received and deliveries made, and the number of hosts involved in
each case. It also outputs the number of messages that were delayed (that is,
not completely delivered at the first attempt), and the number that had at
least one address that failed.

</P>
<P>
The remainder of the output is in sections that can be independently disabled
or modified by various options. It consists of a summary of deliveries by
transport, histograms of messages received and delivered per time interval
(default per hour), information about the time messages spent on the queue,
a list of relayed messages, lists of the top fifty sending hosts, local
senders, destination hosts, and destination local users by count and by volume,
and a list of delivery errors that occurred.

</P>
<P>
The relay information lists messages that were actually relayed, that is, they
came from a remote host and were directly delivered to some other remote host.
A delivery that is considered as a relay by the checking features described in
section 46.4, because its domain is not in <EM>local_domains</EM>,
might still end up being delivered locally under some configurations, and if
this happens it doesn't show up as a relay in the <EM>eximstats</EM> output.

</P>
<P>
The options for <EM>eximstats</EM> are as follows:

</P>

<P>

<P>
<A NAME="IDX1949"></A>
<A NAME="IDX1950"></A>


<H3><A NAME="SEC882" HREF="spec_toc.html#TOC882">-nt</A></H3>
<P>
Suppress the statistics about delivery by transport.

</P>
<P>
<A NAME="IDX1951"></A>


<H3><A NAME="SEC883" HREF="spec_toc.html#TOC883">-h&#60;<EM>n</EM>&#62;</A></H3>
<P>
This option controls the histograms of messages received and deliveries per time
interval. By default the time interval is one hour. If -<EM>h0</EM> is given, the
histograms are suppressed; otherwise the value of &#60;<EM>n</EM>&#62; gives the number of
divisions per hour, so -<EM>h2</EM> sets an interval of 30 minutes, and the default is
equivalent to -<EM>h1</EM>.

</P>
<P>
<A NAME="IDX1952"></A>


<H3><A NAME="SEC884" HREF="spec_toc.html#TOC884">-q0</A></H3>
<P>
Suppress information about times messages spend on the queue.

</P>
<P>
<A NAME="IDX1953"></A>


<H3><A NAME="SEC885" HREF="spec_toc.html#TOC885">-q&#60;<EM>n1</EM>&#62;</A></H3>
<P>
This option sets an alternative list of time intervals for the queueing
information. The values are separated by commas and are in seconds, but can
involve arithmetic multipliers, so for example you can set 3*60 to specify 3
minutes. A setting such as

<PRE>
-q60,5*60,10*60
</PRE>

<P>
causes <EM>eximstats</EM> to give counts of messages that stayed on the queue for less
than one minute, less than five minutes, less than ten minutes, and over ten
minutes.

</P>
<P>
<A NAME="IDX1954"></A>


<H3><A NAME="SEC886" HREF="spec_toc.html#TOC886">-nr</A></H3>
<P>
Suppress information about messages relayed through this host.

</P>
<P>
<A NAME="IDX1955"></A>


<H3><A NAME="SEC887" HREF="spec_toc.html#TOC887">-nr/pattern/</A></H3>
<P>
Suppress information about relayed messages that match the pattern,
which is matched against a string of the following form (split over
two lines here in order to fit it on the page):

<PRE>
H=&#60;host&#62; [&#60;ip address&#62;] A=&#60;sender address&#62; =&#62;
  H=&#60;host&#62; A=&#60;recipient address&#62;
</PRE>

<P>
for example

<PRE>
H=in.host [1.2.3.4] A=from@some.where =&#62;
  H=out.host A=to@else.where
</PRE>

<P>
The sending host name appears in parentheses if it has not been verified as
matching the IP address.
The mail addresses are taken from the envelope, not the headers. This option
allows you to screen out hosts whom you are happy to have using your host as a
relay.

</P>
<P>
<A NAME="IDX1956"></A>


<H3><A NAME="SEC888" HREF="spec_toc.html#TOC888">-t&#60;<EM>n</EM>&#62;</A></H3>
<P>
Sets the `top' count to &#60;<EM>n</EM>&#62;. This controls the listings of the `top &#60;<EM>n</EM>&#62;'
hosts and users by count and volume. The default is 50, and setting 0
suppresses the output altogether.

</P>
<P>
<A NAME="IDX1957"></A>


<H3><A NAME="SEC889" HREF="spec_toc.html#TOC889">-tnl</A></H3>
<P>
Omit local information from the `top' listings.

</P>
<P>
<A NAME="IDX1958"></A>


<H3><A NAME="SEC890" HREF="spec_toc.html#TOC890">-ne</A></H3>
<P>
Suppress the list of delivery errors.

</P>



<H2><A NAME="SEC891" HREF="spec_toc.html#TOC891">53.9 Mailbox maintenance</A></H2>

<P>
<A NAME="IDX1959"></A>
<A NAME="IDX1960"></A>
<A NAME="IDX1961"></A>
The <EM>exim_lock</EM> utility locks a mailbox file using the same algorithm as Exim.
This can be used to prevent any modification of a mailbox by Exim or a user
agent while investigating a problem. The utility requires the name of the file
as its first argument. If the locking is successful, the second argument is run
as a command (using C's <EM>system()</EM> function); if there is no second argument,
the value of the SHELL environment variable is used; if this is unset or empty,
<EM>/bin/sh</EM> is run. When the command finishes, the mailbox is unlocked and the
utility ends. The following options are available:

</P>

<P>

<P>
<A NAME="IDX1962"></A>


<H3><A NAME="SEC892" HREF="spec_toc.html#TOC892">-fcntl (exim_lock)</A></H3>
<P>
Use <EM>fcntl()</EM> locking on the open mailbox.

</P>
<P>
<font color=green>
<A NAME="IDX1963"></A>


<H3><A NAME="SEC893" HREF="spec_toc.html#TOC893">-interval (exim_lock)</A></H3>
<P>
This must be followed by a number, which is a number of seconds; it sets the
interval to sleep between retries (default 3).
</font>

</P>
<P>
<A NAME="IDX1964"></A>


<H3><A NAME="SEC894" HREF="spec_toc.html#TOC894">-lockfile (exim_lock)</A></H3>
<P>
Create a lock file before opening the mailbox.

</P>
<P>
<A NAME="IDX1965"></A>


<H3><A NAME="SEC895" HREF="spec_toc.html#TOC895">-mbx (exim_lock)</A></H3>
<P>
Lock the mailbox using MBX rules.

</P>
<P>
<font color=green>
<A NAME="IDX1966"></A>


<H3><A NAME="SEC896" HREF="spec_toc.html#TOC896">-retries (exim_lock)</A></H3>
<P>
This must be followed by a number; it sets the number of times to try to get
the lock (default 10).
</font>

</P>
<P>
<font color=green>
<A NAME="IDX1967"></A>


<H3><A NAME="SEC897" HREF="spec_toc.html#TOC897">-timeout (exim_lock)</A></H3>
<P>
This must be followed by a number, which is a number of seconds; it sets a
timeout to be used with a blocking <EM>fcntl()</EM> lock. If it is not set (the
default), a non-blocking call is used.
</font>

</P>
<P>
<A NAME="IDX1968"></A>


<H3><A NAME="SEC898" HREF="spec_toc.html#TOC898">-v (exim_lock)</A></H3>
<P>
Generate verbose output.

</P>
<P>
<A NAME="IDX1969"></A>


<H3><A NAME="SEC899" HREF="spec_toc.html#TOC899">-q (exim_lock)</A></H3>
<P>
Suppress verification output.

</P>

<P>
If none of -<EM>fcntl</EM>, -<EM>lockfile</EM> or -<EM>mbx</EM> are given, the default is to
create a lock file and also use <EM>fcntl()</EM> locking on the mailbox, which is the
same as Exim's default. The use of -<EM>fcntl</EM> requires that the file be
writeable; the use of -<EM>lockfile</EM> requires that the directory containing the
file be writeable. Locking by lock file does not last for ever; Exim assumes
that a lock file is expired if it is more than 30 minutes old.

</P>
<P>
The -<EM>mbx</EM> option is mutually exclusive with -<EM>fcntl</EM>. It causes a shared lock
to be taken out on the open mailbox, and an exclusive lock on the file
<EM>/tmp/.<EM>n</EM>.<EM>m</EM></EM> where <EM>n</EM> and <EM>m</EM> are the device number and inode
number of the mailbox file. When the locking is released, if an exclusive lock
can be obtained for the mailbox, the file in <EM>/tmp</EM> is deleted.

</P>
<P>
The default output contains verification of the locking that takes place. The
-<EM>v</EM> option causes some additional information to be given. The -<EM>q</EM> option
suppresses all output except error messages.

</P>
<P>
A command such as

<PRE>
exim_lock /var/spool/mail/spqr
</PRE>

<P>
runs an interactive shell while the file is locked, whereas

<PRE>
exim_lock -q /var/spool/mail/spqr &#60;&#60;End
&#60;<EM>some commands</EM>&#62;
End
</PRE>

<P>
runs a specific non-interactive sequence of commands while the file is locked,
suppressing all verification output. A single command can be run by a command
such as

<PRE>
exim_lock -q /var/spool/mail/spqr \
  "cp /var/spool/mail/spqr /some/where"
</PRE>

<P>
Note that if a command is supplied, it must be entirely contained within the
second argument -- hence the quotes.

</P>

<P><HR><P>
Go to the <A HREF="spec_1.html">first</A>, <A HREF="spec_52.html">previous</A>, <A HREF="spec_54.html">next</A>, <A HREF="spec_59.html">last</A> section, <A HREF="spec_toc.html">table of contents</A>.
</BODY>
</HTML>