Contact Us 1-800-596-4880

Windows Gateway Services Configuration Guide - Mule 3

Select

Latest version: 1.12.0

Windows Gateway Services provides connectivity to proprietary functionality on the Windows platform, and is used by the following connectors:

Windows Gateway Services uses the following technologies and frameworks:

  • ASP.NET Web API exposes an HTTP web API that sends and receives raw messages.

  • OWIN provides the HTTP layer. Open Web Interface for .NET (OWIN) is an open specification for decoupling applications from web server functionality, which provides a layer for making all the HTTP concerns independent of the hosting platform.

  • Katana provides the OWIN Microsoft implementation, which handles self and IIS hosting for OWIN applications.

Before You Begin

  • Java Cryptography Extensions must be installed on the server where Mule is installed. The JCE package is required to allow the Connector to use HTTPS to communicate securely. You can install JCE for your Java version from the Oracle website:

  • To enable TLS 1.2 on servers that run Windows Server 2008 R2, you must create the DisabledByDefault entry in the appropriate subkey (Client, Server) and set it to 0. The entry does not appear in the registry and it is set to 1 by default. TLS/SSL Settings

  • Windows 2008 Server, Windows 2008 R2 Server, or Windows 2012 Server, and .NET Framework 4.5 or later are required for installation.

Installing the Windows Gateway Services

To install Windows Gateway Services:

  1. Download the Windows Gateway Services installer.

  2. Unzip the software distribution.

  3. Double-click the Anypoint-Windows-Gateway-Service.exe file.

  4. Click Options to change the installation location, or click Install to start the installation.

  5. If you are using the MSMQ or Windows PowerShell connectors along with the Windows Gateway Services, copy the Authentication Token that is shown during installation and save it. The Authentication Token is used to configure the connection for those connectors in Studio. If you are not using the MSMQ or Windows Powershell connectors, skip this step.

    1. After you copy the token, click Install.

      After the installation completes, the installer gives you the option to view the readme.txt file, which has additional instructions.

  6. Click Finish to exit.

  7. The installation creates the new Anypoint Gateway Windows service, which the installer starts.

To view the running service in Windows 7, when the Control Panel View by option is set to Small icons, select Control Panel > Administrative Tools > Services. The service appears as Anypoint Gateway in the list.

Configuring the Anypoint Gateway

The default installation location for the Windows Service is c:\Program Files(x86)\Anypoint Gateway for Windows unless you chose another folder when you installed it. This folder contains the Mule.SelfHost.exe executable, the Mule.SelfHost.exe.config configuration file, and PowerShell scripts to automate configuration tasks.

If the configuration file doesn’t appear in the folder, in Windows 7, when the Control Panel View by option is set to Small icons, click Control Panel > Folder Options > View > Show hidden files, folders, and drives.

The executable starts a new web server at port 9333 (default), which accepts only secure connections using HTTPS. You can change the port number where the Gateway listens in the following places within the Mule.SelfHost.exe.config configuration file:

<appSettings>
    <!-- Configure the service to listen on the following address. -->
    <add key="OwinHostAddress" value="https://+:9333/"/>
    ...
</appSettings>
 ...
<system.serviceModel>
    <services>
      <service behaviorConfiguration="routing"
          name="System.ServiceModel.Routing.RoutingService">
        <host>
          <baseAddresses>
            <add baseAddress="https://*:9333/router"/>
          </baseAddresses>
    ...
</system.serviceModel>

This web server uses a self-signed SSL certificate, which is auto-generated during installation. The certificate is in the Certificates (Local Computer) > Personal > Certificates.

The following are examples for creating a valid self-signed certificate to import on the Windows Server. Execute the commands to generate the certificate with OpenSSL from the OpenSSL bin folder:

openssl.exe req -x509 -nodes -days 730 -newkey rsa:2048 -keyout newcert.pem -out newcert.pem -config cert_with_san.txt
openssl.exe pkcs12 -export -out newcert.pfx -in newcert.pem -name "My Cert" -passout pass:mypassword

You must copy the certificate cert_with_san.txt to your bin folder.

You can then register the certificate. If you are using a self-signed certificate, ignore SSL warnings and add the certificate to the truststore used by the client application.

The contents of cert_with_san.txt follows. (This is for localhost or 127.0.0.1 usage.):

[req]
distinguished_name = req_distinguished_name
x509_extensions = v3_req
prompt = no
[req_distinguished_name]
C = US
ST = VA
L = Somewhere
O = MyOrg
OU = MyOU
CN = Anypoint Gateway
[v3_req]
keyUsage = keyEncipherment, dataEncipherment
extendedKeyUsage = serverAuth
subjectAltName = @alt_names
[alt_names]
DNS.1 = localhost
DNS.2 = 127.0.0.1
IP.1 = 127.0.0.1
IP.2 = 127.0.0.1

Because the Windows service relies on http.sys for self-hosting the web server, changes in the port number or SSL certificate require reconfiguring Windows. The Register-SslCert.ps1 PowerShell script in the installation directory handles this task. If the port or certificate changes, run the following command from a PowerShell console:

Register-SslCert.ps1 <certificate-thumbprint> <windows-account> <port>

  • <certificate-thumbprint>: The thumbprint of the SSL certificate. It must be stored in the Personal Folder of the Local Store Account.

  • <windows-account>: Windows User or Group that receives permissions to register the port. The account impersonating the Windows service or console application must be part of this group.

  • <port>: HTTP port (9333 is the default) you set in the configuration file.

Example:

Register-SslCert.ps1 a495cbf8c4af496f1ef81efb224c8097d039f922 everyone 9333

Configuring MSMQ and PowerShell Connector Settings

Security Considerations

For MSMQ and PowerShell connectors running in the Mule ESB, the service first authenticates the call by inspecting the HTTP Authorization header.

The authentication is done through a 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 uses the Gateway to connect to a specific queue sending the security token as specified in this section (the same authorization header applies for PowerShell):

GET: https://localhost:9333/msmq?count=50
Authorization: mule 3nGdw7W+G1fSO2YBEHDmpo4N1Tg=
Mule-Msmq-Queue-Name: .\private$\out
Mule-Api-Version: 1.0

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

<appSettings>
    <!-- Token that must be sent by the Mule connector's client in the Authorization header when accessing the Rest Api. -->
    <add key="mule-auth-token" value="3nGdw7W+G1fSO2YBEHDmpo4N1Tg="/>
</appSettings>

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

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

Impersonating a Windows User

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.

MSMQ Specific Information

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

Windows Gateway Services ASP .NET Web API and Mule ESB with Mule runtime and Jersey HTTP client running on JVM on the OS of your choice

MSMQ Configuration Settings

The following table contains the configuration settings for MSMQ Connector:

Property Usage

invalid-queue-name

The queue name where unreadable messages are moved to.

transaction-timeout

The timeout for processing messages since they were retrieved by the connector. When the cleanup task finds a message with an expired timeout, it moves the message to the main queue so it’s available again (for details, check two phase commit section in the connector’s guide).

invalid-message-timeout

The timeout for invalid messages for when a payload of a message is parsed with an incorrect formatter.

cleanup-delay

The delay of the cleanup task to start looking for expired messages after they got retrieved for processing (for details check the two phase commit section in the connector’s guide).

cleanup-username

(Optional) The user to impersonate when running the cleanup task. If you choose to leave this setting empty then the user account running the service is used.

cleanup-password

(Optional) The password for the user to impersonate when running the cleanup task.

Impersonating a Windows User

When your queue is marked to require authentication, you can impersonate the caller user as specified in the cleanup-username configuration parameter. In addition to this, if you work with a remote queue the connector has a particular header to override this behavior (for details, check the connector’s guide).

Load Balanced Configuration

Windows Gateway Services supports running in a load-balanced configuration to enable fault tolerance. When running multiple gateway services instances, each member must 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 must 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:

  • For a cluster of two machines, the cleanup-delay is set to 0 on machine 1 and 5 on machine 2.

  • For a cluster of 3 machines, the cleanup-delay is set to 0 on machine 1, 3 on machine 2, and 6 on machine 3.

Synchronize machine clocks by NTP or an equivalent mechanism to ensure this offset is applied correctly.

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

<appSettings>
    <!-- MSMQ: Delay in minutes to launch the cleanup process for sub-queues -->
    <add key="cleanup-delay" value="0"/>
</appSettings>
When running in LB configuration, configure Gateway Services 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) must 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 3.9@mule-runtime::msmq-connector.adoc[MSMQ Connector User Guide].

PowerShell Specific Information

This connector has no specific configuration other than the general configuration in Security Considerations.

See Windows Powershell Connector Release Notes for version information.

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

Configuring Dynamics CRM and AX Connectors

Do not modify the service configuration settings that are in the <system.serviceModel> section of the Mule.SelfHost.exe.config configuration file. This section contains necessary settings to provide the routing service to the related connectors.

If you want to change the port where the service is provided, you can update the baseAddress port number within the URL set there, and register the certificate for SSL as described in the Configuring the Anypoint Gateway section to complete the change.

The following configuration section affects these connectors:

<system.serviceModel>
    <services>
      <service behaviorConfiguration="routing"
          name="System.ServiceModel.Routing.RoutingService">
        <host>
          <baseAddresses>
            <add baseAddress="https://*:9333/router"/>
          </baseAddresses>
    ...
</system.serviceModel>

CRM Specific

In addition to the routing service configuration described in the Configuring Dynamics CRM and AX Connectors section, this connector has specific configuration settings.

Configuration settings

The following table contains configuration settings for the CRM connector:

Property Usage

CRM.MaxReceivedMessageSize

The maximum size, in bytes, for a received message that is processed by the channel connected to Microsoft Dynamics CRM Server. For more information, see BasicHttpBinding.MaxReceivedMessageSize Property.

CRM.MaxBufferSize

The maximum size, in bytes, of the buffer used to store messages in memory from the channel connected to Microsoft Dynamics CRM Server. For more information see BasicHttpBinding.MaxBufferSize Property.

See Microsoft Dynamics CRM Release Notes for version information.

For more information on the CRM connector, see the Microsoft Dynamics CRM Connector Guide.

AX Specific

In addition to the routing service configuration described in the Configuring Dynamics CRM and AX Connectors section, this connector has specific configuration settings.

Configuration settings

This table contains the configuration settings for the AX connector:

Property Usage

AX.Metadata.MaxReceivedMessageSize

The maximum size, in bytes, for a received message that is processed by the channel connected to Microsoft Dynamics AX Server targeting the Metadata services (NetTcpBinding.MaxReceivedMessageSize Property).

AX.Metadata.MaxBufferSize

The maximum size, in bytes, of the buffer used to store messages in memory from the channel connected to Microsoft Dynamics AX Server targeting the Metadata services (NetTcpBinding.MaxBufferSize Property).

AX.Metadata.ReceiveTimeout

The value, in milliseconds, that specifies the interval of time provided for a receive operation to complete while using the Metadata services. This value should be greater than zero (Binding.ReceiveTimeout Property).

AX.Metadata.SendTimeout

The value, in milliseconds, that specifies the interval of time provided for a send operation to complete while using the Metadata services. This value should be greater than zero (Binding.SendTimeout Property).

AX.Query.MaxReceivedMessageSize

The maximum size, in bytes, for a received message that is processed by the channel connected to Microsoft Dynamics AX Server targeting the Query services (NetTcpBinding.MaxReceivedMessageSize Property).

AX.Query.MaxBufferSize

The maximum size, in bytes, of the buffer used to store messages in memory from the channel connected to Microsoft Dynamics AX Server targeting the Query services (NetTcpBinding.MaxBufferSize Property).

AX.Query.ReceiveTimeout

The value, in milliseconds, that specifies the interval of time provided for a receive operation to complete while using the Query services. This value should be greater than zero (Binding.ReceiveTimeout Property).

AX.Query.SendTimeout

The value, in milliseconds, that specifies the interval of time provided for a send operation to complete while using the Query services. This value should be greater than zero (Binding.SendTimeout Property).

AX.DocServices.MaxReceivedMessageSize

The maximum size, in bytes, for a received message that is processed by the channel connected to Microsoft Dynamics AX Server targeting the Document services (NetTcpBinding.MaxReceivedMessageSize Property).

AX.DocServices.MaxBufferSize

The maximum size, in bytes, of the buffer used to store messages in memory from the channel connected to Microsoft Dynamics AX Server targeting the Document services (NetTcpBinding.MaxBufferSize Property).

AX.DocServices.ReceiveTimeout

The value, in milliseconds, that specifies the interval of time provided for a receive operation to complete while using the Document services. This value should be greater than zero (Binding.ReceiveTimeout Property).

AX.DocServices.SendTimeout

The value, in milliseconds, that specifies the interval of time provided for a send operation to complete while using the Document services. This value should be greater than zero (Binding.SendTimeout Property).

See Microsoft Dynamics AX Release Notes for version information.

For more information on the AX connector, see the Microsoft Dynamics AX Connector Guide.

Windows Gateway Service Troubleshooting

The Windows Gateway service leverages the built-in .NET tracing system. Tracing messages are sent through switches to listeners, which are tied to a specific storage medium. The listeners for the trace source used by the connector are available in the configuration file:

<sharedListeners>
   <add name="console" type="System.Diagnostics.ConsoleTraceListener" />
   <add name="file" type="System.Diagnostics.TextWriterTraceListener" initializeData="mule.gateway.log" />
   <add name="etw" type="System.Diagnostics.Eventing.EventProviderTraceListener, System.Core, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" initializeData="{47EA5BF3-802B-4351-9EED-7A96485323AC}" />
</sharedListeners>

<sources>
    <source name="mule.gateway">
        <listeners>
            <clear />
            <add name="console" />
            <add name="etw"/>
        </listeners>
    </source>
</sources>

The previous example configures three listeners for the output console, for files, and for Event Tracing for Windows (ETW). The trace source for the connector mule.gateway is configured to output the traces to the console and ETW only.

Changing the Tracing Level

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:

<switches>
    <add name="mule.gateway" value="Information" />
</switches>

Other possible levels are:

  • Error: Output error handling messages

  • Warning: Output warnings and error handling messages

  • Information: Output informational messages, warnings, and error handling messages

  • Off: Disable tracing

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 connecting to the routing service. To get this information at the tracing listeners, enable it using the includeExceptionDetailInFaults attribute from the serviceDebug element. To do this, set its value to true:

<serviceBehaviors>
  <behavior name="routing">
    ...
    <serviceDebug includeExceptionDetailInFaults="true" />
  </behavior>
</serviceBehaviors>

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.

Console tracing (running from command line)

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:

<sources>
    <source name="mule.gateway">
        <listeners>
            <clear />
            <add name="console" />
            ...
        </listeners>
    </source>
</sources>

To run this from the command line, first 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, close this console and restart the Windows service.

Event Tracing for Windows

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:

<sharedListeners>
   <add name="etw"type="System.Diagnostics.Eventing.EventProviderTraceListener, System.Core, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" initializeData="{47EA5BF3-802B-4351-9EED-7A96485323AC}"/>
</sharedListeners>

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

Collect Session Traces

To collect session traces:

  1. Open a Windows console and run this command to start a new session:

    logman start mysession -p {47EA5BF3-802B-4351-9EED-7A96485323AC} -o etwtrace.etl -ets
  2. Run this command to stop the session:

    logman stop mysession -ets

    This generates the etwtrace.etl file with the tracing session data.

  3. Run this command to generate a human readable file:

    tracerpt etwtrace.etl

This command transfers useful information into the dumpfile.xml text file.

For more information, see Tracerpt.