Windows Gateway Services Guide

For these connectors, running in the Mule ESB, the service first authenticates the call by inspecting the HTTP Authorization header as specified in the RFC 2616.

As said, the authentication is done through this unique security token used by both connectors. This token is included on every HTTP request to the Gateway using the Mule scheme. The following example shows how MSMQ leverages the Gateway to connect to a specific queue sending the security token as specified in this section (the same authorization header applies for PowerShell):

The authorization token should match on the connector and the Gateway configuration file. The following configuration setting shows how the token is set within the Gateway configuration file Mule.SelfHost.exe.config :

When you configure the connectors running in the Mule ESB, the authorization token value should be set at the 'Gateway Access Token' configuration setting (accessToken attribute at the connector’s XML configuration).

Note: The installer for the Windows Gateway service automatically generates a cryptographically secure token for use by callers upon first install. This token is displayed and placed upon the clipboard during installation for easy copying into a Mule application.

Users executing the call on behalf of a Gateway-served connector authenticate through two custom HTTP headers, mule-impersonate-username and mule-impersonate-password.

These two headers represent the Windows credentials of an existing user in the Active Directory forest where the Windows Gateway service is running, or a local account on the machine hosting the service. When these HTTP headers are included in an HTTP Request, the Windows Gateway service authenticates and impersonates this user before executing the operation required by the connector. This provides the ability to configure the correct access control list permissions using Windows credentials.

The following diagram shows the interaction of the MSMQ connector with the Gateway, along with the main components used:

Windows Gateway Services supports running in a load-balanced configuration to allow for fault tolerance. When running multiple gateway services instances, each member should be configured to perform MSMQ background jobs at a non-overlapping interval.

MSMQ background job processing is by default performed every 10 minutes starting at zero minutes past the hour. To prevent multiple gateway instances simultaneously attempting to perform cleanup on the queues when running in load-balanced configuration, a setting called cleanup-delay should be specified on each gateway instance. The recommended value to use for this on each machine is (10 / instanceCount) * (instanceNumber - 1) where instanceNumber is an integer value 1..n.

For example, a cluster of 2 machines would use cleanup-delay of 0 on machine 1, 5 on machine 2. A cluster of 3 machines would use cleanup-delay of 0 on machine 1, 3 on machine 2, and 6 on machine 3. Machine clocks should be synchronized by NTP or equivalent mechanism to ensure this offset is applied correctly.

The cleanup-delay setting is found in the Mule.SelfHost.config file:

Note: When running in LB configuration the gateway services should be configured to run as 'Administrator' when the nodes involved (MSMQ, gateways) are under a WORKGROUP but not joined to a DOMAIN. When joined to the same DOMAIN the permissions for each of the nodes and objects involved (queues) should be correctly set by the domain’s administrator.

See MSMQ Connector Release Notes for version information.

For more information on the MSMQ connector, see the MSMQ Connector User Guide.

This connector has no specific configuration other than the general configuration regarding the Security Considerations that are described above.

See MSMQ Connector Release Notes for version information.

For more information on the PowerShell connector, see the Windows PowerShell Connector Guide.

In addition to the routing service configuration described above at the Configuring Dynamics CRM and AX Connector Settings section, this connector has specific configuration described below.

In addition to the routing service configuration described above at the Configuring Dynamics CRM and AX Connector Settings section, this connector has specific configuration described below.

The Windows Gateway Services is configured to log Information events. This is configured under the <switches> element. If you want to log everything, you should use the Verbose level, by changing it in the configuration element shown below.

Configure the levels at switch level in the configuration file:

Other possible levels are:

If you want to trace or debug the routing service within the Windows Gateway Services (for CRM and AX connectors), there is a setting that you can enable to get more details about the error that was generated while hitting the routing service. If you want to get this information at the tracing listeners, then you should enable it using the includeExceptionDetailInFaults attribute from the serviceDebug element. In order to achieve this, you need to set its value to true as shown below:

This setting extends the error message returned by the service and adds an internal stack trace of the cause, which in some scenarios may help you understand what the issue or problem is.

A useful way to troubleshoot issues is to enable the console listener (by default it is, but if not then you should add it to the listeners section shown above), and run the Windows Gateway Services from command line. Within the console you can see real time information which is being traced, like requests, responses and some warnings/errors. These are useful to see if the connector is reaching the Gateway properly, or other possibles causes that could be generating a fault.

To enable the console listener, in case it is not, you need to add it to the listeners collection as shown below:

To run from command line, first you need to stop the Anypoint Gateway service, and then go to the folder where it is installed (by default c:\Program Files(x86)\Anypoint Gateway for Windows) and run the Mule.SelfHost.exe application. This starts running a console and displays tracing events within it in real time.

When you are done troubleshooting, you can simply close this console and restart the windows service back again.

Event Tracing for Windows (ETW) is a very efficient built-in publish and subscribe mechanism for doing event tracing at the kernel level. There is little overhead in using this feature compared to other traditional tracing solutions that rely on I/O for storing the traces in persistence storage such as files or databases. As a built-in mechanism in Windows, many of the operating systems services and components use this feature as well. For that reason, not only can you troubleshoot the application but also many of the OS components involved in the same execution.

In ETW, there are applications publishing events in queues (or providers) and other applications consuming events from those queues in real-time through ETW sessions. When an event is published in a provider, it goes nowhere unless there is a session collecting events on that queue. (The events are not persisted).

The tracing system in .NET includes a trace listener for ETW, EventProviderTraceListener, which you can configure with a session identifier, which ETW uses to collect traces:

In the example, the session is associated with this identifier:
{47EA5BF3-802B-4351-9EED-7A96485323AC}