CatchAllAgent: Exchange 2007 Transport Protocol Agent
=====================================================


Introduction
------------

CatchAllAgent is an Exchange 2007 Transport Protocol Agent. If a message comes in, and a 
recipient of that message does not exist (unknown recipient), the recipient typically gets 
rejected by the Recipient Filtering feature (which is also a Transport Protocol Agent).
The CatchAllAgent can be configured to rewrite the recipient address for unknown recipients
such that such messages end up in a dedicated mailbox. The configuration allows for multiple
domains, but you can only specify a single target address for each of those domains.


Configuration
-------------

The configuration is called config.xml and should be found at the same location of the agent's
assembly (DLL). The contents looks something like this:

<config>
  <domain name="domain1.com" address="catchall@domain1.com" />
  <domain name="domain2.com" address="admin@domain2.com" />
</config>

This says that messages to unknown recipients @ domain1.com should be redirected to
"catchall@domain1.com", and messages to unknwon recipients @ domain2.com should be
redirected to "admin@domain2.com". Recipients that are either known at those domains,
or at other domains (either known or unknown) are unaffected.

Changes to the configuration file will be picked up on the fly. If there is an error
in the configuration file, the (new) content will be ignored.


Installation Steps
------------------

1. Create a directory on your Transport server (either Edge or Internet Facing Hub role)

2. Unzip the ExchangeCatchAll.zip file in that directory

3. Edit the config.xml according to your needs

4. Open the Exchange 2007 Management Shell and run the following command to install 
   the agent, assuming the directory with the CatchAll agent is c:\catchallagent:
   
[PS] C:\catchallagent>install-transportagent -Name "CatchAll Agent" -TransportAgentFactory:CatchAll.CatchAllFactory -AssemblyPath:"C:\catchallagent\CatchAllAgent.dll"

Identity                                           Enabled         Priority
--------                                           -------         --------
CatchAll Agent                                     False           18

WARNING: Please exit Powershell to complete the installation.
WARNING: The following service restart is required for the change(s) to take effect : MSExchangeTransport

5. Now the priority of the CatchAllAgent needs to be smaller that the priority of the Recipient
   Filtering agent. So you first need to figure that out using the get-transportagent task:

[PS] C:\catchallagent>get-transportagent

Identity                                           Enabled         Priority
--------                                           -------         --------
Transport Rule Agent                               True            1
Journaling Agent                                   True            2
RMS Encryption Agent                               False           3
AD RMS Prelicensing Agent                          False           4
Connection Filtering Agent                         True            12
Content Filter Agent                               True            13
Sender Id Agent                                    True            14
Sender Filter Agent                                True            15
Recipient Filter Agent                             True            16
Protocol Analysis Agent                            True            17
CatchAll Agent                                     False           18

   So in this case (Internet facing Hub) the priority of the Recipient Filtering Agent is 16, and since 
   11 is available, that'd be a good pick. Use the following command to set the priority:

[PS] C:\catchallagent>set-transportagent "CatchAll Agent" -Priority:11

WARNING: The following service restart is required for the change(s) to take effect : MSExchangeTransport

6. Now the agent can be enabled:

[PS] C:\catchallagent>enable-transportagent "CatchAll Agent"

WARNING: The following service restart is required for the change(s) to take effect : MSExchangeTransport

7. Restart the Transport service:

   net stop MSExchangeTransport
   net start MSExchangeTransport


Troubleshooting
---------------

The agent supports standard .NET tracing. To enable tracing, you have to add the following 
section to the application configuration file (edgetransport.exe.config):

<configuration>
  <system.diagnostics>
    <trace autoflush="false" indentsize="4">
      <listeners>
        <add name="myListener" 
          type="System.Diagnostics.TextWriterTraceListener" 
          initializeData="traces.log" />
        <remove name="Default" />
      </listeners>
    </trace>
  </system.diagnostics>
</configuration>

The result is that traces will be written to file "traces.log" in the applcation's directory.
There will only be traces for configuration changes, and not when a recipient gets processed.


- Wilbert De Graaf (wilbertdg@hotmail.com)