Advanced Configuration of Axigen - Admin Manual

From Axigen Wiki

The Axigen binary is located in the following paths, based on the operating system used:

• For Linux and Solaris: /opt/axigen/bin/axigen
• For OpenBSD and FreeBSD: /usr/local/bin/axigen
• For NetBSD: /usr/pkg/bin/axigen
• For Windows: C:\Program Files\Axigen Mail Server\axigen.exe

The default initscript path for handling the Axigen daemon is:

• For all supported Linux distributions, except Slackware: /etc/init.d/axigen
• For Linux Slackware: /etc/rc.d/rc.axigen
• For Solaris: /etc/init.d/axigen
• For OpenBSD: /usr/local/bin/axigen.sh
• For NetBSD: /usr/pkg/etc/rc.d/axigen
• For FreeBSD: /usr/local/etc/rc.d/axigen.sh

On some of the supported systems, the initscript has also a configuration file, with the following default path:

• For RPM-based systems: /etc/sysconfig/axigen
• For Gentoo: /etc/conf.d/axigen
• For Debian/Ubuntu: /etc/default/axigen
• For Slackware: /etc/rc.d/rc.axigen.conf

Path to working directory

The -W, --workdir path command line parameter can be used to specify the full path to working directory.

The default value for this parameter is:

• For Linux and Solaris: /var/opt/axigen/
• For BSD systems: /var/axigen/
• For Windows: C:\Program Files\Axigen Mail Server\

Path to configuration file

The -C, --configfile filename command line parameter can be used to specify the path where the server configuration file resides.

The default value for this parameter is:

• For Linux and Solaris: /var/opt/axigen/run/axigen.cfg
• For BSD systems: /var/axigen/run/axigen.cfg
• For Windows: C:\Program Files\Axigen Mail Server\run\axigen.cfg

Command-line parameters

The following command line parameters are available in the current version of Axigen Mail Server. These parameters are common to all platforms.

• -h, --help - Print help about command-line parameters and exit.
• -v, --version - Print the version currently installed and exit.
• --foreground - Run the Axigen Mail Server program in foreground.
• --drop-core path - Specify the full path (maximum length is 240 characters) to an existing directory where to drop the core (section in memory containing relevant information about resident processes). This is useful in case of errors causing the program to exit. No default value is set, meaning the core is not saved by default.
• -L, --license filename - Server license key (LK) binary file. Default to 'workdir'/axigen_lk.bin.
• -A, --admin-passwd password - Set the "admin" password in server registry and exit.
• -K, --check-configuration - Check configuration files, report errors and exit.
• -u, --user username - User's name who executes the server. Default to "axigen'.
• -g, --group groupname - Group's name who executes the server. Default to "axigen".
• -ulimit-n Min=1024, Max=100000 - Maximum number of open file descriptors. Default to 20000.
• -m, --ulimit-v Min=512, Max=4095 - Virtual memory limit in MB. Default to 0 (inherited from environment).
• --mem-reserve Min=12, Max=1024 - Memory used by memory manager module in MB. Default to 200.
• --max-respawns Min=0, Max=30 - Maximum number of accepted faulty processes per minute before exiting. Default to 10.
• --gen-cert certpath [dhpath] - Generates a self-signed certificate and optional a Diffie-Hellman key.
• --gen-cert-cn certCN - The Common Name to be included in the SSL certificate.
• --rmtuning level - Configure resource manager behavior. Possible values: lazy, normal, aggressive, paranoia.

Axigen Working Directory

The Axigen working directory path depends on your operating system:

• For Linux and Solari: /var/opt/axigen/
• For BSD systems: /var/axigen/
• For Windows: C:\Program Files\Axigen Mail Server\

The Axigen Working directory also contains the following:

• ctasd/ - This folder contains the configuration files for Commtouch
• domains/ - This folder contains domains-related files. For each domain a new folder is defined and within each folder contains the domain storage, object storage and message storage files.
• filters/ - This folder contains all the filters defined at the server, domain or account level. The smtpFilters.script file (SMTP Policies are defined in this file) is also located in this folder.
• kas/ - This folder contains the files used by the Kaspersky AntiSpam engine.
• kav/ - This folder contains the files used by the Kaspersky AntiVirus engine.
• log/ - This folder is used to store the log files.
• queue/ - This folder is used to store email messages received and enqueued.
• reporting/ - This folder contains files that the server uses to render reporting charts.
• run/ - This folder contains the Axigen Mail Server current configuration file.
• serverData/ - This folder contains server storage related information.
• templates/ - This folder contains the template files used for sending customized and localized system messages.
• webadmin/ - This folder contains all the files required by the WebAdmin interface.
• webmail/ - This folder contains all the files required by the WebMail interface.
• mobile_ua.cfg - This file contains strings that will identify mobile web browsers.
• axigen_cert.pem - This file contains a self-signed certificate that can be used with SSL-enabled services.
• axigen_dh.pem - This file contains the Diffie-Hellman key, required in order to use ADH ciphers for SSL.

Axigen Configuration File - "axigen.cfg"

The default location for the main Axigen Mail Server configuration file, axigen.cfg, is dependent on the OS platform on which the mail server is installed. Based on these details, the default reference to this path will consist of:

• For Linux and Solaris: /var/opt/axigen/run/axigen.cfg
• For BSD systems: /var/axigen/run/axigen.cfg
• For Windows: C:\Program Files\Axigen Mail Server\run\axigen.cfg

The axigen.cfg file includes the complete specification for Axigen Mail server configuration. Besides containing configuration data specific for Axigen modules, axigen.cfg is also used for specifying the primary domain for Axigen server (primaryDomain).

Using axigen.cfg, you have access to all Axigen Mail Server configuration parameters. Using a text editor, you can manually edit the parameter values and modify the server configuration. The configuration file also contains information on default and possible values and a short explanation for each parameter.

The same options are available when using WebAdmin, except that changes to the configuration are made through the web-based GUI. Detailed information on how to configure each parameter and information on its functions are given in the Configuring Axigen using WebAdmin subsections.

Restrictions

When working with axigen.cfg file, you need to follow the restrictions listed below:

• maximum attribute name length: 64
• maximum attribute value length: 128 (expressed as string in configuration file). Each STRING value is limited to a length of 255 characters.

Definitions

Limits:

• maximum attribute name length: 64
• maximum attribute value length: 8192
• all time attributes (timeouts and time intervals) are specified in seconds
• all data sizes are specified in KB

Syntax:

• empty lines are ignored
• a hash character ("#") introduces a comment to the end of the line
• any block inside /* ... */ is treated as comment
• values cannot be continued across new lines
• values containing spaces or "#" must be quoted using double quotes
• double quotes can be escaped using a blackslash ("\")
• sets of values are declared inside round parentheses ()
• an object or sets of objects are declared inside brackets {}
• attribute names are case-insensitive
• an attribute definition is of form: attributeName = attributeValue

Attribute values:

• simple value with the following base types:
  • UINT - unsigned integer
  • STRING - case insensitive string, may be quoted using double quotes
  • CS_STRING - case sensitive string, may be quoted using double quotes
  • IP - a IPv4 address in decimal numbers-and-dots format, i.e.: 127.0.0.1
  • IP_SET - a set for IPv4 addresses specified in one of the following ways:
    1. IP interval 10.0.0.1-10.0.0.20
    2. IP address/IP mask 10.0.0.1/255.0.0.0
    3. IP address/IP mask size 10.0.0.1/8
  • IP_PORT - a IPv4 address in decimal numbers-and-dots format followed by a ":" char and a decimal port number, i.e.: 127.0.0.1:25
  • CHOICE - a single STRING from a specified set of STRINGs, i.e.: "yes" from ("yes" "no") set
  • CHOICE-SET - means a subset of STRINGs from the specified set of STRINGs; the subset must be specified between round parentheses ()
• set of simple values, a set of base type values except CHOICE and CHOICE-SET, specified between round parentheses ()
• objects, an orderless enumeration of attribute definitions inclosed by brackets {}
• objects set, a set of objects inclosed by round parentheses ()

Some attributes have DEFAULT values (specified below) which are used when the respective attributes are missing from configuration file. If a REQUIRED attribute is omitted from an object this will make the server to ignore the respective object.

The mqview Tool

The mqview tool, available in the Axigen Mail Server package, can be used to view status for messages in the queue.

The Axigen queue contains for each message stored in the queue, besides the message itself, a file with a status report for the message. You can view the status report for the files currently in the Axigen queue using the mqview tool:

/var/opt/axigen/queue/0F/S12BE (Linux and Solaris)
/var/axigen/queue/0F/S12BE (BSD systems)
C:\Program Files\Axigen Mail Server\queue\0F\S12BE (Windows)

Solution 1:

cd /var/opt/axigen/queue/0F

/opt/axigen/bin/mqview @ S12BE

Solution 2:

/opt/axigen/bin/mqview /var/opt/axigen/queue 0F12BE

Each of these commands displays an output similar to the one below:

johnd /var/opt/axigen/queue/00 # mqview @ S5F4E

Mail Queue view of file : ../00/S5F4E
ID : 005F4E
State : RECEIVED
Flags : 00
Last Data Version : 00
Number of RCPTs : 1
Next Send Schedule : As Soon As Possible
Retry Count : 0
Reverse Path : root@localdomain
Authenticated Path : root@localdomain
RCPT information for: johnd@localdomain
State : RECEIVED
Data Version : 00
Filter Info :
Destination mbox: INBOX
Failure Info :
Local Delivery : 

Message Flow Policies - "smtpFilters.script"

The Axigen SMTP Policy system is defined in a single file per installed Axigen mail server and has events for the SMTP Incoming, Outgoing and Processing stages of a mail life cycle. The Policy system contains Message Acceptance Policies and Processing and Relay Policies. The file is known by the server by the means of smtpFiltersFile parameter.

The events defined for the SMTP filters and their contexts are presented bellow:

Event - Context - Occurrence

• onConnect - SMTP Incoming - Called when a new client is connected.
• onEhlo - SMTP Incoming - Called after receiving the EHLO message sent by the client.
• onMailFrom - SMTP Incoming - Called as a result of the MAIL FROM command issued by the client.
• onRcptTo - SMTP Incoming - Called as a result of the RCPT TO command issued by the client
• onHeadersReceived - SMTP Incoming - Called after the message header is received.
• onBodyChunk - SMTP Incoming - Called every time a piece of the mail body is received.
• onDataReceived - SMTP Incoming - Called after receiving the message successfully through the DATA or BDAT commands.
• onRelay - SMTP Outgoing - Called before establishing a relay connection in order to determine the connection parameters.
• onDeliveryFailure - Processing - Called when the mail delivery failed for a certain group of recipients.
• onTemporaryDeliveryFailure - Processing - Called when the mail delivery has temporarily failed for a certain group of recipients.

This language defines a scripting language to be used especially for SMTP filtering. The SMTP process has three different contexts: Incoming, Outgoing and Processing. Thus the behavior of the same filter differs depending on the context to which it is applied. For example the SMTPIn events are triggered only within the SMTP Incoming context.

The message flow is always presented from the Axigen perspective. In other words, the SMTP Incoming context refers to any message that is received by Axigen from any remote host, client or another server. Decisions are made upon the received message on every event. The SMTP Outgoing context refers to messages sent from the Axigen machine to a remote host also using SMTP (Simple Mail Transfer Protocol).

SMTP Policies

Basic structure

The language is structured in blocks of two types: events and methods. The events are predefined blocks that will be executed at specific moments by the server. The methods are custom defined blocks that will be called from the language. Thus the basic structure of a language file is:

event event1 {
  ...
}
event event2 {
  ...
}

Comments inside the script file are allowed using the syntax: #comment until the end of line.

Methods

Beside the custom methods, a number of predefined methods are also available. They are called in the same way and have a predefined behavior. The currently available predefined methods are:

• checkSPF
• checkReverseDNS
• addHeader
• addIfNotExistsHeader
• removeFirstHeader
• removeHeader
• modifyHeader
• modifyIfExistsHeader
• addRcpt
• discardRcpt

A more comprehensive example of a script defined until now, can be:

event onHelo {
  call(heloEvent);
}
method heloEvent {
  call(checkSpf);
  call(addHeader);
}

Variables

After methods and events, the next as level of importance are the variables. They act as input and output to functions and also act as actions to be taken by the SMTP engine. All variables are considered to be string or numbers and can be of three types:

• read-only variables (input variables);
• read-write variables (input/output variables);
• action variables - these variables can be either read-only or read-write but they are in this category because they can cause the SMTP engine to take an action or are involved in an action.

Variable behavior is context-dependent. If a variable is an input variable for the SMTP Incoming context it will be set only in that context and will be "" in the SMTP Outgoing context. Furthermore, a variable will be set only after that variable's value is known. For example, the MailFromDomain variable will be "" in the onConnect and onEhlo events and will be set only in onMailFrom event.

Some variables are set/read by the engine but there are methods for reading/writing them from the code. The reading of a variable implies the comparing of the variable's value with another value or variable. This is done using test functions that form the test block of a conditional block.

Structures

Condition blocks

There are only block, sub-block, if and switch structures. The block structures were defined above. The ‘if’ structure has the following form:

if (conditions) {
  ...
}
else {
  ...
}

The sub-blocks mentioned above are part of the "if" and "switch" structure and as in the case of blocks, start with a "{" and end with a "}".

The switch structure has the following form:

switch (variable) {
  case <value>: {
    ...
  }
  case <value>: {
    ...
  }
  default: {
    ...
  }
}

Both the "if" and the "switch" structures can imbricate a maximum of 16 levels of imbrication. The case statements are exclusive, that means that if a case is matched, after the execution of the block, the switch structure is exited.

Conditions

The conditions are Boolean functions that are used in the "if" and "switch" tests. They split into 2 types: single conditions and logical groups.

The single conditions are as follows:

• is(variable,value) - matches for equality;
• isCase(variable,value) - matches for equality and if strings, the match is case insensitive;
• match(variable,regexp) - regular expression match;
• lessThen(variable,value) - number comparison;
• greaterThen(variable,value) - number comparison;
• greaterOrEqual(variable, value) - number comparison;
• lessOrEqual(variable, value) - number comparison;
• iprange(variable, range) - matches if the variable's value is in range. If the variable is not an ipAddress, the function returns false.

Example of how to define IP ranges:

• 192.168.1.1-192.168.1.10 (range)
• 192.168.1.1/24 (cidr)
• 192.168.1.1/255.255.255.0 (netmask)

The logical groups are:

• not(condition) - negation of a condition;
• allof(condition,condition,...) - similar to an AND between conditions;
• anyof(condition,condition,...) - similar to an OR between conditions.

The logical groups allow a maximum of 16 levels of imbrication.

Functions

The functions can be looked at as keywords from other languages. They are the building blocks of the language and their behavior is hard-coded. The functions available are:

• all the Boolean functions described above;
• call (method) - this executes a predefined of custom defined method. If the method is custom defined, it must be defined in the same script file as the call;
• export (variable) - this function exports a variable name and value to be used in another context. If the variable is custom defined it must be defined in the same script file;
• set (variable, value) - this sets the value of a RW variable;
• return - this function ends the current event or method execution.

SMTP events

The events defined for the SMTP filter and their contexts are:

• onConnect - SMTPIn event
• onEhlo - SMTPIn event
• onMailFrom - SMTPIn event
• onRcptTo - SMTPIn event
• onHeadersReceived - SMTPIn event
• onDataReceived - SMTPIn event
• onRelay - SMTPOut event
• onDeliveryFailure - SMTPProc event
• onTemporaryDeliveryFailure - SMTPProc event

Thus, the structure of the script file is:

# Sample Axigen SMTP Filter 

# the event called when a connection is made to SMTP   	
event onConnect {
  ...
  # statements
}

# the event called when smtp receives EHLO
event onEhlo {
  ...
  call(methodName);
}

method methodName {
  ...
  # statements
}

For example the following code will be applied on the onConnect event and will reject connections from the remote IP 1.2.3.4 with an explanation:

event onConnect {
  call (ruleName);
}
method ruleName {
  if (
    anyOf (
      ipRange (remoteSmtpIP, "1.2.3.4-1.2.3.4")
    )
  ) {
    set (smtpAction, "reject");
    set (smtpExplanation, "IP address not allowed.");
  }
}

Another example applied on the onRcptTo event:

event onRcptTo {
  call (ruleName);
}
method ruleName {
  if (
    anyOf (
      isCase (currentRcptDomain, "example.org")
    )
  ) {
    set (currentRcptRelayHost, "[1.2.3.4]");
  }
}

The above rule will be applied when the "RCPT TO" command is given during the SMTP communication. If the recipient's domain is "example.org" the message will be relayed to the IP address 1.2.3.4.

Methods

Beside the custom methods, there are some predefined ones, they will be called in the same way and will have a predefined behavior.

These are:

• checkSPF
• checkReverseDNS
• checkDNSBL
• addHeader
• addIfNotExistsHeader
• removeFirstHeader
• removeHeader
• modifyHeader
• modifyIfExistsHeader
• addRcpt
• discardRcpt

A more comprehensive example of a script defined until now, can be:

event onHelo {
  call(heloEvent);
} 
method heloEvent {
  call(checkSpf);
  all(addHeader);
}

Variables

To set a variable, the function set is used:

set(SPFResult, "some value")

When a predefined method is called, it usually sets one or more variables as its output and usually requires setting one or more variable as its input. Apart from the predefined variables, custom variables also exist and they can be used later in the code. To define a variable you just set its value:

set(aVariable, "aValue")

The previous function defines a variable named aVariable and sets its value to "aValue".

A custom defined variable has lifetime that lasts until the end of a block. To preserve a variable across blocks and across contexts, the export function is used:

export(aVariable)

The lifetime of a filter with its contexts is per email message so the export function can be used to preserve the value of a variable specific to one email message through different stages of SMTP. For example, at the SMTP Outgoing context, the value of MailFromDomain is not set but can be, if in one of the SMTP Incoming events, an export(MailFromDomain) was made.

Within the SMTP Filter Language, the concept of variable expanding means that, within a string, a variable name may appear and at runtime the name will be replaced by the variable's value. In order for a variable to be expanded, its name must appear between "%" characters. An example of variable expanding is:

event onConnect {
  set(aVariable, "Hello.");
  set(SMTPGreeting, "%aVariable% This is my AXIGEN server");
}

When you connect on the SMTP port, the greeting will be: "Hello. This is my AXIGEN server"

This expanding mechanism also works for comparing two variables:

event onConnect {
  set(aVariable, "value");
  set(bVariable, "value");
  if (is(aVariable,"%bVariable%) {
    set(SMTPAction,"reject");
  }
}

Examples

Bellow is an example of a SMTP policy script with three methods (rules) showing all the events. Each section is explained using comments.

event onConnect {
}

# On this event the Rule1 method will be applied
event onEhlo {
  call (Rule1);
}


event onMailFrom {
}

# Rule2 method will be applied when "RCPT TO" command is given during the SMTP communication 
event onRcptTo {
  call (Rule2);
}


event onHeadersReceived {
}


event onBodyChunk {
}


event onDataReceived {
}

# When the message is going to be relayed the Rule3 method will be applied
event onRelay {
  call (rule3);
}


event onDeliveryFailure {
}


event onTemporaryDeliveryFailure {
}

# The following rule is applied on the onEhlo event
method Rule1 {


# If the connecting IP address is between 192.168.1.2 and 192.168.1.5 allow remote delivery for all users without authentication 
- Axigen becomes open relay if the connecting IP addresses are in the specified range
  if (
    anyOf (
      ipRange (remoteSmtpIP, "192.168.1.2-192.168.1.5")
    )
  ) {
    set (remoteDelivery, "all");
  }
}

# Rule2 can be translated to: if the recipient's domain is axigen.com then add a new recipient to the message
method Rule2 {
  if (            
    anyOf (
      isCase (currentRcptDomain, "axigen.com")
    )
  ) {
    set (currentRcpt, "postmaster@example.com");
    set (currentRcptFolder, "Inbox");
    call (addRcpt);
  }
}

# Rule3 can be translated to: for any message that is to be relayed, because this method is called at the onRelay event, 
use "mail.example.com" in the EHLO command.

method Rule3 {
  set (ehloHost, "mail.example.com");
}