Querying
the Queue
The
Inspector
The
Eraser
The
Defroster
The
Flusher
The
Exporter
Start
and Stop
Configuration
Profile
Management
Local
Mode
Remote
Mode (XQM Agent Configuration and Security)
XMail
SMTP Error Codes
Bugs
? Welcome
to XMail Queue Manager ! |
 |
 |
|
|||
 XMail
Forum |
||||
|
||||
At first: don't be scared about reading manuals! This doc is as short as possible and it will help you to make your life as an XMail Server Admin easier! So let's go ...
XMail Server handles all its incoming and outgoing mail in a single folder called spool.
When you look inside that directory on a standard installation, you see 23 sub folders, numbered from 0 to 22 and 2 other folders called temp and local. Each of the 23 numbered folders has again 23 sub folders inside (0-22). Each of this 2nd level folders ends up in 8 folders named mess, rsnd, froz, slog etc ...
This makes up a total of (23 * 23 * 8) + 2 = 4.234 folders, which XMail Server uses as a queue database for multiple threads.
So XQM was created to have a tool that
- allows you to flatten this multilevel nested structure to a single, easy readable list,
- to view a snapshot of the incoming and outgoing mail flow,
- to inspect messages for detailed content and error diagnostics,
- to monitor message- and queue size,
- to do Remote Queue
Management of multiple non-GUI machines
which run XMail Server ...
|
This function makes a snapshot of the current queue content. XQM spawns multiple threads,. each of them collecting the information of one or more sub tree structures in parallel. When all threads are finished, the spoolfile list is displayed.
The list is sortable by each column header field. Every line starts with an icon that represents the message's current status:
 |
Sending means that it is currently delivered, exactly in this moment. |
 |
Resending means that the message could not be delivered due to a temporary delivery error and is tried again. |
 |
Frozen : If a message was resent a certain number of times, it changes its state to frozen. Frozen messages are not resent anymore. |
When you right-click an entry, you'll get a popup menu, which displays all message related functions of the toolbar for quick access.
Diagnosis
The maybe most important column is the rightmost one called "Diagnosis". It contains a short hint (message tag), that tell you why a message wasn't delivered. E.g. "QUOTA", if the recipient's mailbox was full or "DNS_FAILED?" when a DNS problem is assumed etc.
This Analyzer function is extremely helpful for classifying a bulk of messages quickly at a glance. By sorting the column, you can easily seperate malformed mails from only temporary errors. There is need to dig through each message with the Inspector.
If you are interested in creating user defined message tags, then have a look at the file parse.lib in XQM's main directory. The file can be viewed with any ASCII viewer or editor.
|
The queue inspector helps you to track messages inside your spool directory. It gives you a detailed view of the currently selected mail (=Spoolfile), its corresponding send log (=SLOG File) and some deeper diagnosis info.
Best practice:
- First check the rightmost column called "Diagnosis". In most cases it contains a hint about the reason why a message wasn't delivered. If you need more details or if the column is cleared, continue with the Inspector
- Leave one inspector dialog open and click through the list to display the currently selected message dynamically.
- Open multiple inspectors when you want to compare some messages with each other.
- You can also envoke this tool by double clicking any list entry or by using the right-button popup menu on the listview.
Spoolfiles are RFC822-conform mails with an additional header that contains XMail specific data. Their structure is as follows:
|
|
||
 Header
structure up to version 1.13 |
|||
|
|||
|
|
||
|
Header
structure since version 1.14 |
|||
|
|||
When a message is in the resending or frozen state, XMail creates an individual send log file (=SLOG) for that message. The SLOG contains detailed informations about each try to deliver the mail.
|
|
||
|
Example |
|||
|
|||
|
"Reading
these files looks much more complicated, than it is. Really!"
:-)
|
With every delivery attempt, XMail adds a new entry to the SLOG file. The latest report is always at the bottom of the file.
A SLOG entry
- starts with the
identifier [PeekTime], followed by a timestamp.
- The delivery result is enclosed in << ... >> symbols.
The delivery result
- contains a numeric
ErrCode,
- a verbose description
of the error, called ErrString
- and eventually additional information called ErrInfo.
After that you
get the delivery details,
- like e.g. the
delivery agent (LMAIL for local delivey and SMAIL for
all other mails),
- the delivery mode
(SMTP-Send or SMTP-Receive),
- the mail addresses
of sender and recipient,
- and the SMTP Error Code.
All further deliver attempts are sequentially logged in exaclty the same manner.
So let's parse
our example:
At exactly
26.Feb 2003, 14:07:05 XMail tried to deliver a mail to the domain "marketmix.co".
The delivery failed, because the domain name could not be resolved by
the name server (= invalid server address). This is a temporary delivery
attempt, because maybe it is only a temporary name server problem. The
next try was at 14.22.51. All the relevant things were taken from the
red marked parts.
You see, it's as easy as promised. In most cases its enough to quickly inspect ErrString and the SMTP-Error message.
|
Deletes messages by their state or selection.
If a message still exists after erasing, then it was locked by XMail. Just try again a little later in that case.
|
This very handy function changes the state of frozen messages to sending messages. You won't miss that tool, if you once made configuration changes to your XMail Server, your DNS or network setup and some of your mails got stuck in the queue.
|
When messages are resent, XMail sticks to a clearly defined scheduling. On a standard installation, the sending plan for each messages looks like this:
|
|
||
|
Resend
Scheduling Plan |
|||
|
|||
|
"For
further informations about tweaking the scheduler,
see chapter COMMAND LINE, paragraph [SMAIL] in the XMail Manual." |
If you flush the queue, XMail starts to resend all messages immediately, without taking care for their precalculated scheduling.
Beware:
When using this function, you should keep 2 things in mind:
- Every flush() increases XMail's resend counter. If the counter exceeds 32 (in our upper example), the messages are frozen.
- If not running,
XMail Server is started immediately when pressing the flush button.
Internally flushing is done, by opening a CTRL session and sending an ETRN command to the SMTP service.
CTRL access has to be configured in the Networking dialog if you manage a local queue. When doing Remote Queue Management, the XQM Agent takes care for CTRL access. This assures that password informations are never sent across a network connection.
|
The exporter exports the list content as a plain ASCII list for use with other applications. Makes a mailing list manager's life easier.
Just decide which message type and which fields to export. Futher you can define a field seperator and quoting character. If you need the column names in the 1st line of your export file, check 'with column headers'. Check 'strip <> from addresses', if your export processor doesn't like <recipient@domain.com> type addressing.
|
Starts and stops XMail Server.
|
XQM knows two networking modes, "local" and "remote". As in its name, "local" is limited to your local machine and "remote" means across a network, e.g. your LAN or even the internet. So the first configuration step is to decide the networking mode. You can create multiple config profiles in this dialog.
|
Select a profile:
All saved profiles are available in the pulldown menu, which
allows quick switching in a very comfortable way. The list is sorted alphabetically
and pressing some key will directly jump to the first entry starting with
that letter.
If you manage multiple remote queues, you can also start multiple instances of XQM with different profiles to query all Agents in parallel.
Add a profile:
After your have finished your config settings, you can save
your configuration as a profile by clicking the ADD button.
Delete a profile:
To delete a profile, just select it with the pulldown menue and click
the DEL button.
Rename a profile:
Select the profile, click DEL, click ADD.
Edit a profile:
All changes are automatically saved to the currently selected profile,
when you click the Apply button of the configuration dialog.
Updating happens without further notification. So if you generate a new profile based on an already existing one, remember to click the ADD button to assign a new name to the new profile before pressing Apply. Pressing Apply directly, would update the currently selected profile.
|
Force
MailRoot
During
startup, XQM tries to determine the MailRoot path from its environment
or the registry (on win32 platform). If you enter a path here, all environment
settings are ignored. This is handy when managing multiple queues on the
same machine or when no environment variable is set. Enter the path
without a slash at the end or use the browse dialog.
Force service name (only on win32 platform)
If
you use a non-standard name for the XMail Server service, then
enter it here.This is useful, when managing multiple servers running on
the same machine.
A
note about multiple installations ...
Running
multiple servers requires all further instances to be a XMail Server
>=1.16.
Running multiple instances of XQM Agent requires all further instances
to be >=v1.19. Forcing remote MailRoot and servicename is done in the
Agent's .conf file.
There is no need
to install multiple versions of XQM, since it is capable of profile
management.
CTRL
access
XQM
needs access to the CTRL protocol in order to apply the Queue Flush
Function. If you don't manage a remote host, you'll have to
configure IP and port of the CTRL service, that runs on your local machine.
When managing a remote host, this part is configured in the Agent's .conf
file.
It's good practice to allow CTRL access only from your local machine, e.g. on interface 127.0.0.1. So your sensible CTRL account information is never sent across any network connection.
Number
of threads
XQM
spawns up to 25 threads. Each of them collects the information
from one or more segments of the nested spoolfolder structure in parallel.
Since threads consume resources (like RAM, CPU power ...), the number of threads was made scaleable to allow running XQM on slower machines with the best possible result.
Just experiment with the slider to find out which value fits best for your individual environment. Keep in mind, that the first query is always slower, because the spoolfolder structure is cached for further queries.
|
Remote Queue Management allows you to manage a remote host on the same or another platform. You can e.g. run XQM on Win2000, managing a Linux machine or the other way around. The setup for Remote Queue Management just needs the IP Address or NetBIOS name of the remote host + the Agent's port number (e.g. 8000)
Additionally you need XQM Agent running on the host. XQM and its Agent talk to each other with the XML/RPC (Remote Procedure Call) protocol, which is based on HTTP-requests. That means it can be routed through any firewall, which allows the user defined communication port.
Security:
Generally no password informations are sent across a network connection.
Only predefined, trusted IP-addresses, subnets or machine names
are allowed to speak to the agent. All other requests are rejected. These
trustees can be mixed and are defined in the file xqmagentwin.conf,
which resides on the remote host. Here are some config examples:
|
Scenario
|
XQM
Networking Dialog |
The
Agent's xqmagentwin.conf (or xqmagent.conf on Linux) |
| Only 2 clients (192.168.0.10 and 192.168.0.11) should be able to manage the server (192.168.0.1) |
Remote: 192.168.0.1 |
THREADS=25 |
| All clients in the server's subnet should be able to manage the server. | Remote:
192.168.0.1 Port: 8000 |
THREADS=25 AGENT_HOST=192.168.0.1 AGENT_PORT=8000 AGENT_DYNIP=0 TRUSTED_CIENTS=192.168.0.* CTRL_HOST=127.0.0.1 CTRL_PORT=6017 |
|
Your Server is located somewhere in the internet. You want to manage it from your LAN. Since client and server lease dynamic IP addresses from their ISPs, you use a free dynamic name service, e.g. no-ip.com . The Agent should take care for IP-changes automatically. |
Remote:
servername.no-ip.com Port: 8000 |
THREADS=25 |
The Agent and Dynamic
IP Addresses:
You should keep in mind, that a change of you IP address makes the agent's
service temporary unavailable. The agent binds itself to the new IP, as
soon he detects a change. But XQM will only be able to reconnect, when
your dynamic nameservice client has updated your remote host's DNS cache.
This behavior cannot be influenced or accellerated by the agent itself.
This can lead to a delay between 1 and approx 15 minutes.
The Agent and Threads:
The number of threads
used by the Agent can be scaled with the THREADS varliable
in the .conf file. If it takes very long until XQM gets the results from
its Agent, you should experiment with this value. A thread number between
2 and 8 is recommended for slow machines, or machines with less RAM. Remember
to restart the Agent to apply .conf file changes.
Multiple Agents:
The Agent also understands forced mailroot folders and forced service
names (on Win32 platform), which allows to run multiple Agents in parallel.
See the Agent's .conf file for more details. No - this does not apply
to Agent Smith (Matrix Reloaded ;-)
|
This is a list of the SMTP error messages, that XMail Server uses to report delivery problems. It will help you when tracking undelivered or delayed mails.
Error codes starting with a 4 are temporary errors. In that case XMail retries to deliver the mail. Codes starting with a 5 are final errors without further delivery attempts. SLOG files might also contain error codes of the recipient's SMTP, which are build up in a similar way (see RFC821).
Log entries are not added to the SLOG files, but to the logs which XMail writes to the MailRoot/logs folder. They are listed here for completeness and for your comfort.
My thanks for the original list go to dario@henry.it , who did a lot of work by filtering this informations out of the XMail Server source code.
|
|
||
|
421
Service not available, closing transmission channel
|
|||
|
|||
|
|
||
|
451
Requested
action aborted: local error in processing
|
|||
|
|||
|
|
||
|
452
Mailbox
full
|
|||
|
|||
|
|
||
|
500
Syntax
error, command unrecognized
|
|||
|
|||
|
|
||
|
501
Command not accepted
|
|||
|
|||
|
|
||
|
501
Syntax
error in forward path
|
|||
|
|||
|
|
||
|
501
Syntax
error in return path
|
|||
|
|||
|
|
||
|
503
Bad
sequence of commands
|
|||
|
|||
|
|
||
|
504
Unknown
authentication
|
|||
|
|||
|
|
||
|
504
You
are registered as spammer
|
|||
|
|||
|
|
||
|
505
Your
domain has not DNS/MX entries
|
|||
|
|||
|
|
||
|
550
Relay
denied
|
|||
|
|||
|
|
||
|
550
Account
disabled
|
|||
|
|||
|
|
||
|
550
Mailbox
unavailable
|
|||
|
|||
|
|
||
|
550
String
does not match anything |
|||
|
|||
|
|
||
|
551
Server
use forbidden |
|||
|
|||
|
|
||
|
550
Server
access forbidden by your IP |
|||
|
|||
|
|
||
|
550
Too
many recipients |
|||
|
|||
|
|
||
|
552
Message
exceeds fixed maximum message size |
|||
|
|||
|
|
||
|
557
Message
exceeds fixed maximum message size |
|||
|
|||
|
If you have any additional informations that you'd like to see in that document or if you find any bugs, please send a mail to h_schneider@marketmix.com
All the best,
Harald
