External Agent Properties

This help section describes the External Agent Properties dialog.

Using the External Agent Properties Dialog

This dialog allows editing an External Agent definition. All fields are required except where noted otherwise.

"Description" Tab

Name

Short name which refers to the agent (e.g., "Backscatter Protection Agent").

Description

Description of the agent and usage options. Optional.

"Run" Tab

Agent executable

The agent executable with full path specification, e.g., c:\av\avscan.exe. Click the "..." button or press CTRL-SPACE to select the executable.

Parameters

Edit the parameters passed to the agent. You can add special fields by clicking the button at the right side of the parameters box. For most agents, you will have to add the {EMAILFILESPEC} special field, which will be replaced by the actual file path of the temporary copy of the tested email ORF creates when it calls the agent, e.g., the parameter

will be turned into

assuming the Path for temporary email files is set as c:\orftemp\ (the EML file name is randomly generated and differs for each email). The explanation for the special fields is available below.

"Role" Tab

ORF is primarily a spam filter and its whitelists prevent legitimate emails from being rejected by excluding them from blacklist tests. However, some External Agents may filter viruses or have other email security role, so you might want these agents to check all emails, including whitelisted ones. You can achieve this by assigning the proper role to the External Agent, so it will be excepted from most whitelist tests.

Spam Filter Role

Use this role if the agent was designed to catch spam emails only and thus should not be excepted from whitelists.

Anti-Virus or Other Email Security Role

Use this role if the agent should be excepted from (most) whitelists, e.g., because the agent filters email for viruses or other malicious/forbidden content.

Note that the agent role makes difference only if the Whitelist Exceptions are enabled for External Agents.

"Logging" Tab

Catch and log agent output on hit/error

Most command-line software write information to the console (these outputs are known as "stdout" and "stderr", which are separate outputs, but normally displayed merged by the console). Set these checkboxes to get ORF to log these outputs when a hit or error occurs. ORF always logs the stdout and stderr output streams merged.

Include file name in the messages

ORF passes temporary email files to External Agents. Set this checkbox to include the name of these files in log messages (on hit or error). This can come in handy if the agent software records the file name in its own logs, so you can easily match the ORF event log entry with the agent's log entry.

"Exit Code" Tab

Various actions can be performed based on the exit code (a.k.a. return code, same as ERRORLEVEL in system batch files). Edit the exit code and action assignments as described below.

At least one exit code must be specified for the agent.

Default action

Specify a default action for all exit codes which will be used when there is no explicit action assignment for an exit code.

Working with exit codes

Set the checkbox of the exit code that you want to activate or clear the checkbox to de-activate. Click the New button to add a new exit code to the list. To modify an existing exit code, click Modify. Exit codes can be deleted using the Delete button or the Delete key.

Using the Exit Codes And Actions Dialog

See the Exit Codes And Actions section.

Special Fields

You can use the following special fields with the agent parameters.

ORF encloses parameters between double quotes. Double quotes inside the field data are tripled, e.g., if {SENDER} is garfield"lazy"[email protected], it is passed to the agent as "garfield"""lazy"""[email protected]. Most language runtimes (such as C#/.NET) deal with tripled quotes correctly, but your mileage may vary.