Installing ServiceControl

Every component in the Particular Service Platform, including ServiceControl, needs to be downloaded and installed.

After installation, there is no ServiceControl instance running yet. These instances can be installed, upgraded, and removed by making use of the ServiceControl Management Utility. This utility is launched as the final step in the installation process and is also available via the Windows Start Menu.

Prerequisites

The ServiceControl installation has the following prerequisites:

• Microsoft .NET 4.7.2 Runtime

Planning

ServiceControl Management provides a simple way to set up one or more ServiceControl instances (error, audit, and monitoring). For production systems, it is recommended to limit the number of instances per machine to one of each type. The ability to add multiple instances of the same type on a single machine is primarily intended to assist development and test environments.

See ServiceControl Capacity Planning and Hardware Considerations for more guidance.

Installing ServiceControl instances

There are three types of ServiceControl instances that can be installed using the ServiceControl Management utility. As the error and audit instance usually go side-by-side, they are installed and configured at the same time.

1. Open the ServiceControl Management Utility in the Windows start menu.
2. Click the New button at the top-right and a popup window appears.
3. Select either Add ServiceControl and Audit instances or Add monitoring instance.
4. Provide a name and transport.
   1. The default name commonly used is Particular.ServiceControl.
      The name is used to derive names for the error and audit instances. The name of each instance can be adjusted from its default if required.
   2. The transport should match the endpoint's transport. If a transport is not available, a transport adapter can be used.
5. For additional instance settings, open the ServiceControl and ServiceControl Audit sections.
   1. The name of the instance can be altered, the defaults for error and audit are Particular.ServiceControl and Particular.ServiceControl.Audit.
      1. The name for the error instance is particularly important to enable plugins to send information to ServiceControl.
      2. If multiple instances for different systems are installed on the same server, a name like Particular.SystemName could be an option as well.
   2. Select the appropriate user account.
      Be aware that ServiceControl instances will run as Windows Services in the background.
   3. Be aware of the port numbers as these are used by ServicePulse and ServiceInsight to connect to ServiceControl.
   4. Configure the retention period for each instance.
   5. Configure the name of the queue that messages should arrive in.
      This queue is important to endpoints that send error and audit messages to these ServiceControl instances, as well as plugins.
   6. If needed, configure forwarding queues.
   7. Full-text search can be turned off for performance reasons.

A monitoring instance differs from error and audit instances in its configuration:

1. There is no configuration for storage as it only stores data in memory.
2. There is no forwarding queue as the messages are specific to ServiceControl monitoring.
3. The queue to forward messages to that can't be processed, as described in monitoring setup.

After configuring an error, audit and monitoring instance for the SQL Server transport, the ServiceControl Management Utility should look similar to this:

Upgrading ServiceControl instances

Whether a new version of ServiceControl is available can be verified in the ServicePulse user interface. A new version can then be downloaded and installed.

ServiceControl Management will display the instances of the ServiceControl service installed. If any ServiceControl instance is running on an outdated version, an upgrade link will be shown next to the version label.

To upgrade the service, click the upgrade link next to the service name.

Clicking the upgrade link will:

• Prompt for additional required information, i.e. new mandatory settings introduced in the newer version
• Stop the service
• Remove the old binaries for ServiceControl and the configured transport
• Run the new binaries to create required queues
• Start the service

ServiceControl plugins

Endpoint plugins like heartbeats and custom checks require sending information to ServiceControl. The name of the queue is the exact name of the error instance.

See Install Heartbeats Plugin and Install Custom Checks Plugin for more information.

Migrating to a new host

These are the steps to perform to migrate an instance of ServiceControl to another host:

1. Ensure the same Windows version is used on the new machine as storage is not compatible between Windows versions.
2. Stop and disable the current instance of ServiceControl in the Windows Service Manager.
3. Install and configure a new instance of ServiceControl using the same name on the new server.
4. Ensure the name is identical
5. Stop the newly installed instance of ServiceControl.
6. Copy the data from the previous instance to the new instance server (moving the data is not recommended).
7. Start the new service.
8. Remove the old instance of ServiceControl.

Things to remember:

• First update the current instance to the latest version.
• Optionally, use the same installer as the current version. Database schemas are not guaranteed to be compatible between different versions.
• Optionally, script ServiceControl installations via powershell instead of running installers manually

ServiceControl configuration settings are accessible via the Service Control Management Utility or by navigating to the configuration files on the file system stored in ServiceControl.exe.config, ServiceControl.Audit.exe.config, and ServiceControl.Monitoring.exe.config.

Removing ServiceControl

To perform a clean uninstallation of ServiceControl from a machine:

1. Remove each ServiceControl instance using ServiceControl Management (or PowerShell)
2. Uninstall ServiceControl Management using Add or Remove programs

Remove ServiceControl instances

To remove a ServiceControl instance, click the Advanced Options button and select Remove. If applicable, select the option to remove the database and logs directories. This will stop the running instance (if it is running) and remove all files related to the instance from the local file system.

Remaining artifacts

Even after a ServiceControl instance has been removed, there are artifacts left behind. Each ServiceControl instance leaves queues in the configured transport. The queue names will depend on the configuration of the ServiceControl instance.

• instance name - control messages for the ServiceControl instance
• instance name.errors - control messages that the ServiceControl instance was not able to process
• instance name.staging - temporary failed messages while they are being retried
• audit queue name - messages that have been processed by endpoints and then forwarded to the audit queue. These messages have not yet been ingested by the ServiceControl instance.
• error queue name - messages that failed processing in endpoints and have passed immediate and delayed retries. These messages have not yet been ingested by the ServiceControl instance.
• audit log queue name if audit log forwarding was configured - messages that have been ingested from the audit queue, processed by this ServiceControl instance, and then forwarded to the audit log queue.
• error log queue name if error log forwarding was configured - messages that have been ingested from the error queue, processed by this ServiceControl instance, and then forwarded to the error log queue.

If the option to delete the database/log folders was not selected when removing the instance, then these folders and their contents are left on disk.

Uninstall ServiceControl Management

To uninstall ServiceControl Management, use the Apps & features settings in Windows.