You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Improve documentation around Windows failover cluster and MSMQ (#7881)
* Improve documentation around Windows failover cluster and MSMQ
This PR improves the documentation on how to set up ServiceControl when using Windows failover cluster and MSMQ
* Add link to the cluster configuration from the transport settings
* Add details around MSMQ and clustering to the ThroughputDataQueue setting
* Update review date
* Add missing slash
* Update deploying-servicecontrol-in-a-cluster.md
* Adding Brandon's findings
* Another pass
* Another pass
* Update configuration.md
* Update transports.md
* Revisions and other fixes
---------
Co-authored-by: Brandon Ording <[email protected]>
Copy file name to clipboardExpand all lines: servicecontrol/deploying-servicecontrol-in-a-cluster.md
+26-57Lines changed: 26 additions & 57 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -3,79 +3,48 @@ title: Deploying ServiceControl to a Cluster
3
3
summary: A guide to deploying ServiceControl on a Windows failover cluster
4
4
related:
5
5
- servicecontrol/troubleshooting
6
-
reviewed: 2024-11-01
6
+
reviewed: 2025-10-22
7
7
---
8
8
9
-
> [!NOTE]
10
-
> ServiceControl only supports active/passive clusters. Clustering might not be required as cloud hosting and enterprise virtualization layers provide high availability and data redundancy features and message queueing ensures no messages are lost.
11
-
12
9
The following procedure is a high-level guide on how to deploy ServiceControl onto a fault-tolerant cluster using Windows Failover Clustering.
13
10
14
11
> [!NOTE]
15
12
> This guide assumes that MSMQ is the underlying transport. Other transports work as long as these are deployed on a different machine. In that case, skip the MSMQ-specific steps.
16
13
17
-
## Basic setup
18
-
19
-
* Set up a failover (active/passive) Windows cluster:
20
-
*[Windows Server 2008](https://blogs.msdn.microsoft.com/clustering/2008/01/18/creating-a-cluster-in-windows-server-2008/)
21
-
*[Windows Server 2012 R2, Windows Server 2012, Windows Server 2016](https://docs.microsoft.com/en-us/windows-server/failover-clustering/create-failover-cluster)
22
-
* Install ServiceControl on each node, adding it as a "generic service" using the cluster manager. This means that ServiceControl will failover automatically with the cluster.
23
-
* Set up an MSMQ cluster group. A cluster group is a group of resources that have a unique DNS name and can be addressed externally like a computer.
24
-
* Add the ServiceControl generic clustered service to the MSMQ cluster group:
25
-
* Ensure it depends on MSMQ and the MSMQ network name
26
-
* Check "use network name as computer name" in the service configuration
27
-
28
-
Once set up, the ServiceControl queues will be available on the cluster. The server name will be the MSMQ network name, not to be confused with the cluster name.
29
-
30
-
More information is available on [Message Queuing in Server Clusters](https://technet.microsoft.com/en-us/library/cc753575.aspx).
31
-
32
-
## Database high availability
14
+
> [!NOTE]
15
+
> ServiceControl only supports active/passive clusters.
33
16
34
-
The RavenDB database must be located in *shared storage* that is highly available and fault tolerant. Shared storage does not mean a network share but shared cluster storage that allows low latency and exclusive access. Access to the data should always be 'local', although physically that data could be stored on a SAN. When this disk is mounted, RavenDB must be configured to use that location. See [Customize RavenDB Embedded Location](configure-ravendb-location.md) for more information on how to change the ServiceControl database location.
17
+
## Infrastructure setup
35
18
36
-
## ServiceControl detailed configuration
19
+
1. Create a [Windows Failover Cluster](https://learn.microsoft.com/en-us/windows-server/failover-clustering/create-failover-cluster?pivots=failover-cluster-manager),
20
+
1. Create a [Message Queuing role on the cluster](https://learn.microsoft.com/en-us/windows-server/failover-clustering/create-failover-cluster?pivots=failover-cluster-manager#create-clustered-roles-in-failover-cluster-manager)
21
+
1. Install ServiceControl on each node of the cluster.
22
+
1. Add the ServiceControl Windows Service as a Generic Service resource to the MSMQ cluster role.
23
+
1. Ensure it depends on the MSMQ role and the MSMQ network name
24
+
1. After setting up the dependencies, check the "Use Network Name as computer name" option
37
25
38
-
Once the failover cluster is created and ServiceControl is installed, configure ServiceControl to run in a clustered environment.
26
+
Before bringing the service resource online, all of the [required queues](/servicecontrol/queues.md#queue-setup) must be created and given the appropriate permissions manually in the cluster.
39
27
40
-
> [!NOTE]
41
-
> The following steps must be applied to all ServiceControl installations on every node in the cluster.
28
+
### Database high availability
42
29
43
-
### URL ACL(s)
30
+
The internal ServiceControl RavenDB database must be located in a shared storage that is highly available and fault tolerant. Shared storage does not mean a network share, but a cluster storage that allows low latency and exclusive access.
31
+
Access to the data should always be local, although physically that data could be stored on a SAN. When this disk is mounted, ServiceControl must be configured to use that location.
44
32
45
-
ServiceControl exposes an HTTP API that is used by ServicePulse and ServiceInsight. URL ACL(s) must be [defined on each cluster node](/servicecontrol/setting-custom-hostname.md). The URL must be set to the `cluster name` and the ACL set to give permissions to the `Service Account` running ServiceControl.
33
+
## ServiceControl configuration
46
34
47
-
> [!NOTE]
48
-
> The default installation of ServiceControl locks down access to `localhost` only. Once the URL ACL is changed from `localhost` to the `cluster name` ServiceControl is accessible from the network.
35
+
The following settings must be applied to all ServiceControl instances on every node in the cluster.
49
36
50
37
### Configuration
51
38
52
-
ServiceControl configuration must be customized by changing the following settings:
53
-
54
-
*`DbPath` to define the path to the shared location where the database will be stored
55
-
*`Hostname` and `port` to reflect `cluster name` and `port`
56
-
*`audit` and `error` queues to include the `cluster name`;
57
-
58
-
The following is a sample ServiceControl configuration file (ServiceControl.exe.config):
39
+
The ServiceControl configuration must be customized by changing the following settings:
59
40
60
-
```xml
61
-
<configuration>
62
-
<appSettings>
63
-
<addkey="ServiceControl/DbPath"
64
-
value="drive:\SomeDir\" />
65
-
<addkey="ServiceControl/Hostname"
66
-
value="clusterName" />
67
-
<addkey="ServiceControl/Port"
68
-
value="33333" />
69
-
<addkey="ServiceBus/AuditQueue"
70
-
value="audit@clusterName" />
71
-
<addkey="ServiceBus/ErrorQueue"
72
-
value="error@clusterName" />
73
-
<addkey="ServiceBus/ErrorLogQueue"
74
-
value="error.log@clusterName" />
75
-
<addkey="ServiceBus/AuditLogQueue"
76
-
value="audit.log@clusterName" />
77
-
</appSettings>
78
-
</configuration>
79
-
```
41
+
- The database path needs to set to the path to the shared location of the database.
42
+
-`ServiceControl/DBPath` for error instances
43
+
-`ServiceControl.Audit/DBPath` for audit instances
44
+
- The host name needs to be set to the MSMQ network name
45
+
-`ServiceControl/HostName` for error instances
46
+
-`ServiceControl.Audit/HostName` for audit instances
47
+
-`Monitoring/HttpHostName` for monitoring instances
48
+
- The `ServiceControl/RemoteInstances` setting should use the MSMQ network name to refer to the audit instance
80
49
81
-
See [Customizing ServiceControl Configuration](/servicecontrol/servicecontrol-instances/configuration.md) for more information.
50
+
See [Customizing ServiceControl Configuration](/servicecontrol/servicecontrol-instances/configuration.md) for more information on each setting.
Copy file name to clipboardExpand all lines: servicecontrol/servicecontrol-instances/configuration.md
+3-2Lines changed: 3 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,7 +2,7 @@
2
2
title: Error Instance Configuration Settings
3
3
summary: Categorized list of ServiceControl Error instance configuration settings.
4
4
component: ServiceControl
5
-
reviewed: 2024-06-24
5
+
reviewed: 2025-10-22
6
6
redirects:
7
7
- servicecontrol/creating-config-file
8
8
---
@@ -137,6 +137,7 @@ The maximum allowed time for the process to complete the shutdown.
137
137
|**SCMU field**| N/A |
138
138
139
139
| Environment/Installation type | Type | Default value |
140
+
|---|---|---|
140
141
| Containers | TimeSpan |`00:00:05` (5 seconds) |
141
142
| Installation via PowerShell (on Windows) | TimeSpan |`00:02:00` (2 minutes) |
142
143
| Installation via ServiceControl Management Utility (SCMU) (on Windows) | TimeSpan |`00:02:00` (2 minutes) |
@@ -525,7 +526,7 @@ The queue on which throughput data is received by the ServiceControl Error insta
525
526
526
527
In most instances these settings do not need to be modified.
527
528
528
-
If running multiple setups of the Platform Tools (i.e. multiple versions of ServiceControl error and monitoring instances) then modify these settings so that the queue on each monitoring instance is matched to the queue of its error instance.
529
+
If running multiple setups of the Platform Tools (i.e. multiple versions of ServiceControl error and monitoring instances), then modify these settings so that the queue on each monitoring instance is matched to the queue of its error instance.
529
530
530
531
If using [MSMQ transport](/transports/msmq) and the monitoring instance is installed on a different machine than the ServiceControl error instance, only the monitoring instance setting needs to be modified to include the machine name of the error instance in the queue address.
To configure MSMQ as the transport, ensure the MSMQ service has been installed and configured as outlined in [MSMQ configuration](/transports/msmq/#msmq-configuration).
168
167
169
-
> [!IMPORTANT]
170
-
> When [ServiceControl instances are installed on a different machine than an endpoint](/transports/msmq/routing.md#when-servicecontrol-is-installed-on-a-different-server)`queuename@machinename` addresses must be used.
171
-
172
168
> [!NOTE]
169
+
> Any settings that specify a queue name for a queue that is not located on the same machine as the ServiceControl instance must use `queuename@machinename` addresses to refer to that queue.
170
+
171
+
> [!WARNING]
173
172
> MSMQ transport is not available when running ServiceControl on containers.
Specifies a URI path of the instance mapping file. Relative paths are assumed to be file paths.
53
53
54
-
55
54
snippet: InstanceMappingFile-UriPath
56
55
57
-
## When ServiceControl is installed on a different server
56
+
## Queues that are not configured with the instance mapping file
58
57
59
-
The [instance mapping file](#instance-mapping-file) will have no effect on the error, audit, metrics, and plugin queues, so if a ServiceControl instance is installed on a different machine than the endpoint the physical mapping must be specified during configuration using `queuename@machinename` addresses:
58
+
The [instance mapping file](#instance-mapping-file) will have no effect on the error, audit, metrics, or plugin queues. If those queues are located on a different machine, then the physical mapping must be specified during configuration using `queuename@machinename` addresses:
When [overriding the default routing](/nservicebus/messaging/send-a-message.md#overriding-the-default-routing) to a queue on a different server the machine name must also be provided:
82
+
When [overriding the default routing](/nservicebus/messaging/send-a-message.md#overriding-the-default-routing) to a queue on a different server, the machine name must also be provided:
0 commit comments