Smtp Gateway Configuration
Jump to navigation
Jump to search
Back: CSharp Reference Implementation
In the sample above, the <Service> and <Type> tags specifies {FullTypeName, AssemblyName}
Table of Contents
Gateway Configuration Settings
Configuration File
The SMTP Gateway currently retrieves operational settings and flags from an Xml Configuration file. You give the Gateway the path to this configuration file during installation.
A sample (and full featured) configuration file is checked into the source tree under csharp\gateway\SmtpAgent\SmtpAgentConfig.xml
Path to the Configuration File
To operate, the Smtp Gateway must know the path to its configuration file. You do this when you attach the Gateway to Smtp Server using the registerGateway.bat script.
You can configure a single SMTP Server (service) to run multiple virtual SMTP virtual servers. You can attach a separate SMTP Gateway to each of these instances. Each gateway instance has an associated Service Instance Number and configuration file.
Because SMTP Server is a native process, you have to supply the gateway with its configuration file path using non-.NET techniques. The registerGateway.bat script writes basic bootstrap properties into a COM property bag attached to each installation of the SMTP Gateway. For example, the developer gateway install script (csharp\gateway\devinstall\install.bat) does the following:
call registerGateway.bat script 1 %destbin%\DevAgentConfig.xml
- The magic number 1 is the service instance number (1 for default)
Currently, the gateway does not automatically detect changes in configuration, so you must restart SMTP Service if you change the configuration for a running system (iisreset).
The root element of your config file is:
/SmtpAgentConfig
Domain & Address
Every SMTP Gateway is responsible for a set of domains. These are the same domains you configured your Smtp Service to manage. Two configuration choices exist. Static or Dynamic domains. Choose one. Static domains are for installations that do not change often. Dynamic domains are for installations that will have a large volume of domains that change often such as large HISP bringing on a new domain daily.
Static Domains
SmtpAgentConfig/Domain/ (Required)
<SmtpAgentConfig> <Domain>redmond.hsgincubator.com</Domain> <Domain>nhind.hsgincubator.com</Domain>
Dynamic Domains
Resolve domains from configuration service.
SmtpAgentConfig/Domains/ (Required)
The domain resolver operates as a SOAP proxy client.
/SmtpAgentConfig/Domains/ServiceResolver__ (Required)
| Child |
Required |
Description |
| AgenName |
Y |
Agent name identifier |
| ClientSettings/Url |
Y |
Url of the Domain Service |
| CacheSettings/Cache |
N |
true or false. Default is false |
| CacheSettings/CacheTTLSeconds |
N |
Cache lifetime in seconds |
<SmtpAgentConfig>
<Domains>
<ServiceResolver>
<AgentName>DirectBridge1</AgentName>
<ClientSettings>
<Url>http://localhost:6692/DomainManagerService.svc/Domains</Url>
</ClientSettings>
<CacheSettings>
<Cache>true</Cache>
<CacheTTLSeconds>20</CacheTTLSeconds>
</CacheSettings>
</ServiceResolver>
</Domains>
Domain Manager
You can configure the gateway to retrieve domain settings from the Configuration Service. The gateway retrieve settings only for the domains listed in the config file (above).
/SmtpAgentConfig/DomainManager
| Child |
Required |
Description |
| Url |
Y |
Url of the Domain Service |
| MaxReceivedMessageSize |
Y |
In bytes. Default - no limit |
| Secure |
N |
Use Windows Authentication. Default - false |
| ReceiveTimeout |
N |
Seconds. How long to wait for a response. Default: 10 minutes (WCF) |
| SendTimeout |
N |
Seconds. How long to wait for request transmission. Default: 1 minute (WCF) |
...
<DomainManager>
<Url>http://localhost:6692/DomainManagerService.svc/Domains</Url>
</DomainManager>
Address Manager
Optional.
When configured with an Address Manager, the gateway verfies that all domain address - i.e. addresses belonging to domains the gateway manages - exists. It does so by looking up the address using the AddressManager service.
The Gateway verified addresses in both directions.
- If a sender of an outgoing message is unregistered, the gateway rejects the message
- If some domain recipients of an incoming message are unregistered, the gateway removes them from the SMTP Envelope RCPTO.
- If no domain recipients can be verified, the Gateway rejects the message
- If the DSN features have been enabled in the Notification section then failure DSN's will be bounced back to the internal senders indicating why the receiver cannot be contacted such as security or trust failures.
/SmtpAgentConfig/AddressManager
| Child |
Required |
Description |
| Url |
Y |
Url of the Address Manager Service |
| MaxReceivedMessageSize |
Y |
In bytes. Default - no limit |
| Secure |
N |
Use Windows Authentication. Default - false |
| ReceiveTimeout |
N |
Seconds. How long to wait for a response. Default: 10 minutes (WCF) |
| SendTimeout |
N |
Seconds. How long to wait for request transmission. Default: 1 minute (WCF) |
| Settings |
N |
Optional settings for this AddressManager |
/SmtpAgentConfig/AddressManager/Settings
| Child |
Required |
Description |
| EnableDomainSearch |
N |
true or false. Default is false. Set to true will validate an email address as true if the address exists in the config store's address table or if the email host exists in the config stores Domain table. In both cases the address or domain must be enabled. |
...
<AddressManager>
<Url>http://localhost:6692/DomainManagerService.svc/Addresses</Url>
<Settings>
<EnableDomainSearch>true</EnableDomainSearch>
</Settings>
</AddressManager>
Public Cert Resolution
You can configure the gateway to resolve public certificates from:
- DNS
- A machine store - and typically, only in debug/test environments.
- From the Middle Tier ConfigService
- PluginResolvers (the following are included in the reference implementation):
- LdapCertResolver
Your production deployments will typically use DNS.
You can use multiple resolvers. The Gateway will try them in order until one succeeds.
/SmtpAgentConfig/PublicCerts (Required)
Dns Certificate Resolution
Resolve public certificates using DNS.
/SmtpAgentConfig/PublicCerts/DnsResolver
| Child |
Required |
Description |
| ServerIP |
Y |
IP Address of the DNS server to send Dns requests to |
| BackupServerIP |
N |
IP Address of the DNS server to try if the primary throws fails (exceptions) |
| Timeout |
N |
In Milliseconds. Default 5000 |
| Cache |
N |
true or false. Default is false |
| ResolveFromRoot |
N |
Some DNS servers do not support CERT requests. The resolver will resolve CERTS directly from certificate domain's root servers. Default is false. (NY Impl) |
...
<PublicCerts>
<DnsResolver>
<ServerIP>127.0.0.1</ServerIP>
<Timeout>5000</Timeout>
</DnsResolver>
Machine Store
Public certs stored on the local machine.
/SmtpAgentConfig/PublicCerts/MachineResolver
| Child |
Required |
Description |
| Name |
Y |
The name of the certificate store. |
| Location |
N |
LocalMachine (default) or CurrentUser |
...
<PublicCerts>
<MachineResolver>
<Name>NHINDExternal</Name>
</MachineResolver>
Config Service
Resolve private certs from the Configuration Service.
/SmtpAgentConfig/PrivateCerts/ServiceResolver
The certificate resolver operates as a SOAP proxy client.
/SmtpAgentConfig/PrivateCerts/ServiceResolver/ClientSettings (Required)
| Child |
Required |
Description |
| Url |
Y |
Url of the Certificate Service |
| MaxReceivedMessageSize |
Y |
In bytes. Default - no limit |
| Secure |
N |
Use Windows Authentication. Default - false |
| ReceiveTimeout |
N |
Seconds. How long to wait for a response. Default: 10 minutes (WCF) |
| SendTimeout |
N |
Seconds. How long to wait for request transmission. Default: 1 minute (WCF) |
...
<PublicCerts>
<ServiceResolver>
<ClientSettings>
<Url>http://localhost:6692/CertificateService.svc/Certificates</Url>
</ClientSettings>
</ServiceResolver>
PluginResolver Certificate Resolution
Resolve public certificates using PluginResolvers.
/SmtpAgentConfig/PublicCerts/PluginResolver/Definition
| Child |
Required |
Description |
| TypeName |
Y |
.Net type implementing this plugin. It is a qualified type name in the following format: Assembly Name, TypeName |
| Settings |
N |
Optional settings for this plugin. |
LdapCertResolver Plugin
Optional Plugin implemented Settings defined for LdapCertResolver Plugin. Please note: If you hope to be able to query LDAP Certificates (externally in another HISP's LDAP store) you will need to enable this plugin. Use the same IP you are using for the DNS Resolver and add the section <PluginResolver> just after the <dnsresolver> section as shown in the codebox below. A reboot is required after altering this.
/SmtpAgentConfig/PublicCerts/PluginResolver/Definition/Settings
| Child |
Required |
Description |
| ServerIP |
N |
IP Address of the DNS server to send Dns requests to. Will use machines network interface configured DNS servers if not supplied. |
| BackupServerIP |
N |
(Not released. In source code.) IP Address of the DNS server to try if the primary throws fails (exceptions). |
| Timeout |
N |
In Milliseconds. Default 5000 |
| Cache |
N |
true or false. Default is false |
...
...
<PublicCerts>
<DnsResolver>
<ServerIP>127.0.0.1</ServerIP>
<Timeout>5000</Timeout>
</DnsResolver>
<PluginResolver>
<Definition>
<TypeName>Health.Direct.ResolverPlugins.LdapCertResolverProxy, Health.Direct.ResolverPlugins</TypeName>
<Settings>
<ServerIP>127.0.0.1</ServerIP>
</Settings>
</Definition>
</PluginResolver>
Private Key Resolution
You can configure the gateway to resolve private certificates from:
- The Config Middle Tier service
- From a Machine Store.
You can use multiple resolvers. The Gateway will try them in order until one succeeds.
/SmtpAgentConfig/PrivateCerts (Required)
Config Service
Resolve private certs from the Configuration Service.
/SmtpAgentConfig/PrivateCerts/ServiceResolver
The certificate resolver operates as a SOAP proxy client.
/SmtpAgentConfig/PrivateCerts/ServiceResolver/ClientSettings (Required)
| Child |
Required |
Description |
| Url |
Y |
Url of the Certificate Service |
| MaxReceivedMessageSize |
Y |
In bytes. Default - no limit |
| Secure |
N |
Use Windows Authentication. Default - false |
| ReceiveTimeout |
N |
Seconds. How long to wait for a response. Default: 10 minutes (WCF) |
| SendTimeout |
N |
Seconds. How long to wait for request transmission. Default: 1 minute (WCF) |
...
<PrivateCerts>
<ServiceResolver>
<ClientSettings>
<Url>http://localhost:6692/CertificateService.svc/Certificates</Url>
</ClientSettings>
</ServiceResolver>
Machine Store
Resolve private certs stored from machine storage.
/SmtpAgentConfig/PrivateCerts/MachineResolver
| Child |
Required |
Description |
| Name |
Y |
The name of the certificate store. |
| Location |
N |
LocalMachine (default) or CurrentUser |
...
<PrivateCerts>
<MachineResolver>
<Name>NHINDPrivate</Name>
</MachineResolver>
Anchor Resolution
You can configure the gateway to resolve anchors from the Configuration Service, a local machine store or from ABBI (Blue Button) trust bundles.
You can configure your Gateway use multiple resolvers. The Gateway will try them in order until one succeeds.
You can also use the Plugin MultiSourceResolver (Gateway Version 1.2.0.2 and later) to configure the Gateway to try multiple *child* anchor resolvers. The MultiSourceResolver will combine the anchors discovered by its children into a single list.
The plugin BundleResolver will resolve ABBI (Blue Button) and other trust bundles from configured bundle Urls.
/SmtpAgentConfig/Anchors (Required)
Config Service Anchor Store
Resolve private certs from the Configuration Service.
/SmtpAgentConfig/Anchors/ServiceResolver
The certificate resolver operates as a SOAP proxy client.
/SmtpAgentConfig/Anchors/ServiceResolver/ClientSettings (Required)
| Child |
Required |
Description |
| Url |
Y |
Url of the Certificate Service |
| MaxReceivedMessageSize |
Y |
In bytes. Default - no limit |
| Secure |
N |
Use Windows Authentication. Default - false |
| ReceiveTimeout |
N |
Seconds. How long to wait for a response. Default: 10 minutes (WCF) |
| SendTimeout |
N |
Seconds. How long to wait for request transmission. Default: 1 minute (WCF) |
...
<Anchors>
<ServiceResolver>
<ClientSettings>
<Url>http://localhost:6692/CertificateService.svc/Anchors</Url>
</ClientSettings>
</ServiceResolver>
Machine Store
Anchors stored on the local machine.
/SmtpAgentConfig/Anchors/MachineResolver
| Child |
Required |
Description |
| Incoming |
Y |
Settings for resolving incoming anchors |
| Outgoing |
Y |
Settings for resolving outgoing anchors |
/SmtpAgentConfig/Anchors/MachineResolver/Incoming (Required)
| Child |
Required |
Description |
| Name |
Y |
The name of the certificate store. |
| Location |
N |
LocalMachine (default) or CurrentUser |
/SmtpAgentConfig/Anchors/MachineResolver/Outgoing (Required)
| Child |
Required |
Description |
| Name |
Y |
The name of the certificate store. |
| Location |
N |
LocalMachine (default) or CurrentUser |
...
<Anchors>
<MachineResolver>
<Incoming>
<Name>NHINDAnchors</Name>
</Incoming>
<Outgoing>
<Name>NHINDAnchors</Name>
</Outgoing>
</MachineResolver>
</Anchors>
Plugin Anchor Resolvers
Gateway V1.2.0.2 and later come with the following plugin anchor resolvers:
- MultiSourceAnchorResolver
- BundleResolver
The resolvers are implemented in Health.Direct.ResolverPlugins.dll. This should be deployed in your Gateway bin.
MultiSourceAnchorResolver
[V1.2.0.2] and later.
The MultiSourceAnchorResolver plugin combines the anchors resolved by one or more child resolvers into a single list.
Each child is always tried. This plugin is useful when you wish to resolve anchors from multiple sources, such as your default config service AND those published for ABBI (Blue Button)
<Anchors> <PluginResolver> <Definition> <TypeName>Health.Direct.ResolverPlugins.MultiSourceAnchorResolver, Health.Direct.ResolverPlugins</TypeName> <Settings> <ServiceResolver> <ClientSettings> <Url>http://localhost/ConfigService/CertificateService.svc/Anchors</Url> </ClientSettings> .....Resolver settings... </ServiceResolver> <BundleResolver> ...Resolver settings.... </BundleResolver> </Settings> </Definition> </PluginResolver> </Anchors>
Bundle Resolver (ABBI Blue Button)
[V1.2.0.2] and later.
Use the bundle resolver to resolve configured anchor bundles for domains and/or addresses.
- Make sure your Config Service and Database schema was upgraded to support Bundles
- You can use the ConfigConsole.exe to configure bundles.
- Type *commands bundle* to get a list of bundle management commands
- You configure an *owner* to trust an anchor bundle pointed at by a Url. *Owner* can be either a domain or an address-- just like you configure anchors in the config service.
The BundleResolver caches downloaded bundles. Use the CacheTTLSettings property below to control cache duration. In production, you should set the Cache setting to 1 day or greater.
<Anchors>
<PluginResolver>
<Definition>
<TypeName>Health.Direct.ResolverPlugins.MultiSourceAnchorResolver, Health.Direct.ResolverPlugins</TypeName>
<Settings>
<BundleResolver>
<ClientSettings>
<Url>http://localhost/ConfigService/CertificateService.svc/Bundles</Url>
</ClientSettings>
<CacheSettings>
<Cache>true</Cache>
<NegativeCache>true</NegativeCache>
<CacheTTLSeconds>86400</CacheTTLSeconds>
</CacheSettings>
<MaxRetries>1</MaxRetries>
<Timeout>30000</Timeout>
<VerifySSL>true</VerifySSL>
</BundleResolver>
<ServiceResolver>
<ClientSettings>
<Url>http://localhost/ConfigService/CertificateService.svc/Anchors</Url>
</ClientSettings>
<CacheSettings>
<Cache>true</Cache>
<NegativeCache>true</NegativeCache>
<CacheTTLSeconds>60</CacheTTLSeconds>
</CacheSettings>
</ServiceResolver>
</Settings>
</Definition>
</PluginResolver>
</Anchors>
Policy Engine
These settings control how the Gateway resolves certificates during public and private certificate resolution and trust resolution.
/SmtpAgentConfig/CertPolicies/[Public, Private, Trust]
See Policy Management for configuring policy filters.
<CertPolicies> <Public> <ClientSettings> <Url>http://localhost/ConfigService/DomainManagerService.svc/CertPolicies</Url> </ClientSettings> <CacheSettings> <Cache>true</Cache> <NegativeCache>true</NegativeCache> <CacheTTLSeconds>60</CacheTTLSeconds> </CacheSettings> </Public> <Private> <ClientSettings> <Url>http://localhost/ConfigService/DomainManagerService.svc/CertPolicies</Url> </ClientSettings> <CacheSettings> <Cache>true</Cache> <NegativeCache>true</NegativeCache> <CacheTTLSeconds>60</CacheTTLSeconds> </CacheSettings> </Private> <Trust> <ClientSettings> <Url>http://localhost/ConfigService/DomainManagerService.svc/CertPolicies</Url> </ClientSettings> <CacheSettings> <Cache>true</Cache> <NegativeCache>true</NegativeCache> <CacheTTLSeconds>60</CacheTTLSeconds> </CacheSettings> </Trust> </CertPolicies>
Cryptography
/SmtpAgentConfig/Cryptographer
| Child |
Required |
Description |
| DefaultEncryption |
N |
Options:
|
| DefaultDigest |
N |
Options:
|
...
<Cryptographer>
<DefaultEncryption>AES128</DefaultEncryption>
<DefaultDigest>SHA256</DefaultDigest>
</Cryptographer>
Trust Model
These settings control how the Gateway verifies X509 certificates.
/SmtpAgentConfig/Trust
| Child |
Required |
Description |
| MaxIssuerChainLength |
N |
Resolve the issuance chain for each cert (including intermediaries) to this depth. Default: 4 |
| RevocationCheckMode |
N |
Controls how certificate revocations are checked.
|
| Timeout |
N |
When doing revocation checking, the Chain Builder will attempt to download CRL (revocation lists) from their source Urls. This sets a Timeout used by the chain builder when downloading CRLs. Default: System defined (Windows). Recommeded. |
The trust section can be omitted from the config file and all defaults will be used. Here is an example Trust section.
...
<Trust>
<MaxIssuerChainLength>4</MaxIssuerChainLength>
<RevocationCheckMode>Online</RevocationCheckMode>
<Timeout>2000</Timeout>
</Trust>
Notifications (Acks)
You can configure the gateway to automatically issue processed MDN notifications for those incoming messages that request them.
As of version 1.1.0.0 MDN notifications can be configured to follow the Implementation Guid for Delivery Notifications in Direct
DSN codes defined by the monitor service can be found in DSN Notification CSharp
/SmtpAgentConfig/Notifications
| Child |
Required |
Description |
| AutoResponse |
N |
Automatically send acks - if requested (using MDN request header). Default: false |
| AlwaysAck |
N |
Send Acks even if not requested. Note: Acks will be sent only if AutoResponse is true. |
| Text |
N |
Standard plain text explanation sent with each ack. |
| ProductName |
N |
The name of this product. Used to build the Reporting-UA header for an MDN. |
| AutoDsnFailureCreation |
N |
Always or TimelyAndReliable. The TimelyAndReliable option is default. TimelyAndReliable option indicates edge client must request delivery notifications. DSN style notifications include failure to resolve public certificates, failure to chain up to a trust anchor, failure to receive a timely processed MDN, and failure to receive a timely dispatched MDN. To receive DSNs for failed public certificate resolution and trust anchor chaining AutoDsnFailureCreation must be either set to Always. Or set to TimelyAndReliable and the sending client has requested delivery notification by including the following header. Disposition-Notification-Options: X-DIRECT-FINAL-DESTINATION-DELIVERY=optional,true |
| GatewayIsDestination |
N |
true or false. Default false. When true gateway will a generate dispatched MDN. When false final destination is responsible for dispatched MDN if requested. See Implementation Guid for Delivery Notifications in Direct to request a dispatched mdn |
The AutoDsnFailurCreation 1.1.0.0 feature list:
- Compatible with 1.0.0.* gateway.
- Notifies edge client of failures as DSN messages. Untrusted recipients will generate failed DSN messages if configured or requested. If not requested and not configured results will be the same as a V1 gateway. Note in V1 partial trusted recipient lists are delivered to trusted recipients without any negative notification. Careful analysis of the log files reveal the partial delivery. If all recipients are untrusted the message ends in the bad messages folder.
...
<Notifications>
<AutoResponse>true</AutoResponse>
<AlwaysAck>true</AlwaysAck>
<Text>Message Delivery Notification</Text>
<GatewayIsDestination>true</GatewayIsDestination>
</Notifications>
Routing
The gateway implements simple message routing based on an address's type.
All addresses maintained in the Config System (middle tier)can have an associated type for the address. You can set a route for each address type. Each route can have one or more receivers - the Gateway will automatically loadbalance over them.
/SmtpAgentConfig/IncomingRoutes
| Child |
Required |
Description |
| Route |
Y |
One or more Routes |
The Gateway supports two types of routes:
- Folder Routes
- Plugin Routes
Folder Routes
The Gateway places messages in destination folders/fileshares.
/SmtpAgentConfig/IncomingRoutes/Route
| Child |
Required |
Description |
| AddressType |
Y |
Address Type (string) |
| CopyFolder |
Y |
Directory path |
For redundancy and loadbalancing, you can associate multiple CopyFolders with a single route.
Plugin Routes
The Gateway creates an instance of a .NET Type in an Assembly you provide. It hands messages to this Type - which can do whatever it wants with it.
The type must implement IReceiver<ISmtpMessage>. See samples in code (csharp\gateway\smtpagent\SmtpMessageForwarder.cs) and in the smtpAgent.tests unit tests see HttpReceiver in the TestRouter.cs file.
/SmtpAgentConfig/IncomingRoutes/PluginRoute
| Child |
Required |
Description |
| AddressType |
Y |
Address Type (string) |
| Receiver |
Y |
Contains the plugin receiver definition |
Config Sample
<IncomingRoutes>
<Route>
<AddressType>BANANA</AddressType>
<CopyFolder>\\share1\drop\banana</CopyFolder>
<CopyFolder>\\share2\drop\banana</CopyFolder>
</Route>
<Route>
<AddressType>POTATO</AddressType>
<CopyFolder>C:\drop\dest1</CopyFolder>
<CopyFolder>C:\drop\dest2</CopyFolder>
<CopyFolder>C:\drop\dest3</CopyFolder>
</Route>
<PluginRoute>
<AddressType>SMTP</AddressType>
<Receiver>
<TypeName>Health.Direct.SmtpAgent.SmtpMessageForwarder, Health.Direct.SmtpAgent</TypeName>
<Settings>
<AddressType>SMTP</AddressType>
<Server>foo.xyz</Server>
<Port>33</Port>
</Settings>
</Receiver>
<Receiver>
<TypeName>Health.Direct.SmtpAgent.SmtpMessageForwarder, Health.Direct.SmtpAgent</TypeName>
<Settings>
<AddressType>SMTP</AddressType>
<Server>bar.xyz</Server>
<Port>39</Port>
</Settings>
</Receiver>
</PluginRoute>
</IncomingRoutes>
If a particular receiver fails for any reason, the router will automatically try one of the alternatives till success, or all alternatives are exhausted(the router will pick alternatives randomly).
Message Wrapping
Mail transport headers typically travel in the clear. To protect transport headers, the Gateway "wraps" messages.
__/SmtpAgentConfig
| Child |
Required |
Description |
| WrapOutgoing |
N |
Boolean. Default: True. Automatically Wrap outgoing messages in message/rfc822 wrapper. |
| AllowNonWrappedIncoming |
N |
Boolean. Default: True. Accept messages that were not wrapped. True by default to allow for interop with S/MIME done by mail clients themselves - e.g. Thunderbird & Outlook. |
Message Processing
These settings control how the messages are processed:
- Outgoing Messages
- Incoming Messages
- Bad (Rejected) Messages
- Internal Relay
You use settings to:
- Control whether messages are actually relayed
- For Debugging - whether a copy of the message is dropped in a local folder
Outgoing Messages
Outgoing messages are sent by THIS domain to other domains. Messages will be:
- Signed
- Encrypted
To actually have your email sent to the Internet, set EnableRelay to true.
/SmtpAgentConfig/Outgoing
| Child |
Required |
Description |
| CopyFolder |
N |
Path to the folder where the gateway puts a copy of trusted outgoing messages (encrypted) To stop copying messages, remove the CopyFolder element. |
| EnableRelay |
N |
true or false. If false, outgoing messages are not put on the wire. Default: true |
...
<ProcessOutgoing>
<CopyFolder>C:\inetpub\mailroot\outgoing</CopyFolder>
<EnableRelay>false</EnableRelay>
</ProcessOutgoing>
Incoming Messages
Incoming messages are sent by other domains TO this one. Messages will be:
- Decrypted
- Have Signatures Validated
If the Gateway accepts a message AND Relay is Enabled:
- It will attempt to Route the message (see Routing section above).
- If no Route matches, the decrypted message will be returned to SMTP Server, which will proceed with its pipeline.
- The SMTP Pipeline could have a registered persistance store such as POP3 or the standard "Drop" folder
- OR, the server may have been set up to forward messages to a Smart Host
/SmtpAgentConfig/Incoming
| Child |
Required |
Description |
| CopyFolder |
N |
Path to the folder where the gateway places a copy trusted incoming messsages (decrypted) To stop copying messages, remove the CopyFolder element. |
| EnableRelay |
N |
true or false. If false, incoming messages are not put on the wire. Default: true |
...
<ProcessIncoming>
<CopyFolder>C:\inetpub\mailroot\incoming</CopyFolder>
<EnableRelay>false</EnableRelay>
</ProcessIncoming>
Bad Messages
Bad messages are messages the Gateway rejects. Reasons for the rejection could include:
- Malformed/non-SMIME compliant messages
- Encryption/Decryption failed
- Signature creation/verification failed
- Certificate Resolution failed - such as over DNS
- Certs are un-trusted
- Message is from an untrusted source
- Target user address does not exist (in Config System)
- Etc
You can save a copy of failed messages in a diagnostics folder.
/SmtpAgentConfig/BadMessage
| Child |
Required |
Description |
| CopyFolder |
N |
Path to the folder where the gateway placed reject messages To stop copying messages, remove the CopyFolder element. |
...
<BadMessage>
<CopyFolder>C:\inetpub\mailroot\badMail</CopyFolder>
</BadMessage>
Capturing Raw Messages
You can capture messages in the raw - outgoing and incoming - before the gateway processes them. This is very useful for debugging.
You should disable this option on production.
/SmtpAgentConfig/Raw
| Child |
Required |
Description |
| CopyFolder |
N |
Path to the folder where the gateway placed every message To stop copying messages, remove the CopyFolder element. |
...
<RawMessage>
<CopyFolder>C:\inetpub\mailroot\raw</CopyFolder>
</RawMessage>
Internal Relay
You typically setup the SMTP Gateway to run in front of your e-mail server. The gateway treats all messages originating from within the domain as outgoing messages.
Similarly, the gateway treats all messages sent by addresses in external domains as incoming. Incoming messages must be signed and ecrypted, or else the are automatically dropped.
In certain configurations, you may want to have the gateway also function as your email server. To do so, outgoing messages with recipients in locally managed domains must be looped back and reprocessed as incoming messages.
This option is especially useful for test and staging deployments. The gateway accomplishes this loopback by placing a copy of the outgoing message in the SMTP Server's pickup folder.
By default, the gateway will not allow internal message delivery.
When no address manager is configured and no routes configured, MDNs will only be issued if the EnableRelay flag is set.
/SmtpAgentConfig/InternalMessage
| Child |
Required |
Description |
| CopyFolder |
N |
Path to the Smtp Server's pickup folder To stop copying messages, remove the CopyFolder element |
| EnableRelay |
N |
true or false. Default: false |
...
<InternalMessage>
<CopyFolder>C:\inetpub\mailroot\Pickup</CopyFolder>
<EnableRelay>false</EnableRelay>
</InternalMessage>
MDN Monitor
You can configure the gateway to track outgoing messages and incoming notifications.
In 1.1.0.0 a MdnMonitorWinSrv Windows service is added as an installation option. The service monitors tracked outgoing messages and correlated notifications. If a message is not delivered timely according to the Implementation Guid for Delivery Notifications in Direct, a failed delivery status notification will be sent to the outgoing message sender.
/SmtpAgentConfig/MdnMonitor
| Child |
Required |
Description |
| Url |
Y |
Url of the Domain Service |
| MaxReceivedMessageSize |
Y |
In bytes. Default - no limit |
| Secure |
N |
Use Windows Authentication. Default - false |
| ReceiveTimeout |
N |
Seconds. How long to wait for a response. Default: 10 minutes (WCF) |
| SendTimeout |
N |
Seconds. How long to wait for request transmission. Default: 1 minute (WCF) |
...
<MdnMonitor>
<Url>http://localhost:6692/MonitorService.svc/Dispositions</Url>
</MdnMonitor>
Logging
The Gateway writes debug and status information to a log file.
You can configure the log file using a Log File Settings section.
You can use this configuration to set log levels as well as optionally bubble log data into the Event Log, where it can be monitored using SCOM/MOM packs.
You can also replace the logging mechanims with your own, by implementing Health.Direct.Common.Diagnostics.ILogger. You can plugin your implementation using
Auditing
The Gateway maintains an Audit Log of Accepted & Rejected messages, both inbound and outbound. It does so using an Auditor.
The Auditor is an object that implements the Health.Direct.Common.Diagnostics.IAuditor interface.
The default auditor writes to the Windows EventLog as shown in the configuration below.
You can customize Audit Log capture by implementing your own auditor. You do so by implementing
Health.Direct.Common.Diagnostics.IAuditor, and then changing the Gateway configuration file:
<SmtpAgentConfig> ... <Container> <Component> <Service>Health.Direct.Common.Diagnostics.IAuditor, Health.Direct.Common</Service> <Type>Health.Direct.Common.Diagnostics.EventLogAuditor, Health.Direct.Common</Type> <Scope>Singleton</Scope> </Component> </Container> ...
In the sample above, the <Service> and <Type> tags specifies {FullTypeName, AssemblyName}