XML Format Reference

Introduction

This reference reports details about the format PostArmor uses to store its configuration. There are many possible files that use this format - at least 2, the global configuration and a user-related one -, most of the reference applies to all of them, except when explicitly stated. The format itself is based on the XML specs, and as such conforms to specific rules, even though it's considered for private use of the application and doesn't adhere to any particular defined standard.
Internally, the NanoXML Lite library (© Marc De Scheemaecker) has been used: while very fast, it has the limitation that nodes can have either children or #PCDATA, but not both, so the same applies to all the definitions below. This is anyway a perfectly acceptable limitation for the environment the application is working in.

XML Tags definition

POSTARMOR

It's the "root" tag for the format, and the container for all the subsequent tags. It creates the internal contexts (global or user-related) where the evaluations take place

Attributes

name	string	The context's name (global or user's name)
version	string	The actual version of the context (unused at the moment, useful for future updates, default is 0.0)
lastdate	date	The date (in RFC 822 format) when the file was saved last time.
locx	integer positive	The X location of the settings window.
locy	integer positive	The Y location of the settings window.

Children

FILTERINFO, OPTIONS, ADDRESSBOOK, USERS, MESSAGES, FILTERS

#PCDATA

none

FILTERINFO

An informational tag: it's not used at the moment.

Attributes

none

Children

none

#PCDATA

An informational string

OPTIONS

Runtime options applied to the running evaluations: the user-related ones have precedence over the global ones.

Attributes

deldays	integer positive	The number of days a message can stay on hold: after this period, it's automatically deleted. Default 1
threshold	integer positive	Minimum score to consider a message as spam. scores below are accepted and pass through. Default 10
verify	integer positive	If non-zero, check sender address and assign this score to the message if negative. Default 0
highscore	integer positive	Minimum score to automatically delete a message without keeping it on the server. Default 99
dns	String	Specifies a DNS server to use for sender verification, bouncing, etc.
report	YES/NO	Generate a report message when new messages are left on the server

Children

none

#PCDATA

none

USERS

A container for all the <ACCOUNT> tags. It's only found in the global configuration, has no sense in the user-related ones.

Attributes

none

Children

ACCOUNT

#PCDATA

none

ADDRESSBOOK

A container for the <SENDER> tags. Mail from the addresses/domains here are accepted unconditionally.

Attributes

none

Children

SENDER

#PCDATA

none

BLACKBOOK

A container for the <SENDER> tags. Mail from the addresses/domains here are rejected unconditionally.

Attributes

none

Children

SENDER

#PCDATA

none

MESSAGES

A container for the <MSG> tag. It's only found in user-related contexts, as there are no global messages.

Attributes

none

Children

MSG

#PCDATA

none

FILTERS

A container for <RULESET> tags. For each RULESET, the calculated weight is added to the final result.

Attributes

none

Children

RULESET

#PCDATA

none

ACCOUNT

This tag defines the details of the user account: it contains all the information necessary to connect to the external mail server for this particular user.

Atttributes

proxyuser	string	Name of the user that will connect to the proxy. It's also the name of the configuration file.
user	string	Name of the user on the external mail server
server	string	Name or IP address of the external mail server
type	string	Type of mail server: only POP supported at this time
port	integer positive	Port the external server uses to communicate. Default 110
address	string	Address that has to appear in the messages considered "good"
password	string (encoded)	Password to check the account: the value is encrypted for security reasons
autocheck	integer positive	Minutes between automatic checks of the mailbox: if 0, auto check is disabled
locx	integer positive	The X location of the messages window.
locy	integer positive	The Y location of the messages window.

Children

none

#PCDATA

none

SENDER

Marks a (partial or complete) address that the user marks to be definitely "good" or "bad": addresses marked this way will jump over all checks defined in <FILTER>

Attributes

none

Children

none

#PCDATA

An address (partial or complete) of a mail sender that can be accepted/rejected unconditionally.

MSG

Details of a message read from the server, evaluated and kept on hold; these data are saved so that they don't need to be re-read from the server every time.
CAUTION: this tag is normally maintained by the software itself: don't modify it unless you don't know exactly the consequences.

Attributes

uid	string	The unique ID f the message on the server
size	integer positive	The size of the message on the server
date	date	The date the message was read the first time: it's used to calculate the number of days on hold
score	integer	the score assigned when the message was evaluated
from	string	The sender of the message
subject	string	The subject of the message
replyto	string	The Reply-To header of the message (if any)
returnpath	string	The Return-Path header of the message (if any)

Children

none

#PCDATA

none

RULESET

It represent a container for <RULE> tags. It also defines how the children RULEs have to be combined:

A relation OR will apply the weight if just one of the RULEs checks positive;
A relation AND will apply the weight if and only if all the RULEs check positive;
A relation ADD will apply the weight at every positive check of the RULEs, adding the results together.

Attributes

relation	OR, AND or ADD	The type of relation that applies to the RULEs
weight	integer	The weight that has to be assigned to positive check of the RULE(s). Can be both positive (enforce spam checking) or negative (more permissive)
name	string	The name of the set
enabled	YES/NO	Flag to define if this set is enabled or not

Children

RULE

#PCDATA

none

RULE

This tag specifies a single check to be done on one header of the message under examination (or optionally all of them). The simplest check uses the literal expression contained in the #PCDATA section and verifies if it's present in the content, without taking in account the case. A more powerful check is done with the Regular Expression option set: in that case the expression (in a form familiar to Perl programmers) can match a variety of possibilities, and is case sensitive (library is © The Apache Software Foundation).
Result is positive when match

contains If the header(s) contain(s) the specified string (or expression)
noContains If the header(s) doesn't contain the specified string
userAddress If the header(s) contain(s) the user address as specified in <ACCOUNT>
noUserAddress If the header(s) doesn't contain the user address

Attributes

match	contains noContains userAddress noUserAddress	Match type of the check string
regexp	YES/NO	Checks using normal literals or regular expressions (Perl- or grep-like)
header	string	The name of the header or "Any" to indicate that all headers have to be checked

Children

none

#PCDATA

Data to check the desired header against: if the "regexp" flag is false, the check is case-insensitive, if true case matters. This is ignored if checks are against user address.