nservicebusservicecontrol

Table of Contents

1. Description
2. Setup requirements
   • Beginning with nservicebusservicecontrol
3. Usage - Configuration options and additional functionality
   • Service Control Instances
   • Service Control Monitoring Instances
4. Reference - An under-the-hood peek at what the module is doing and how
5. Limitations - OS compatibility, etc.
6. Contributing

Description

The nservicebusservicecontrol module installs and manages Service Control along with Service Control Instances.

ServiceControl is the backend web api used for monitoring and replaying of messages for nservicebus endpoints.

Setup Requirements

The nservicebusservicecontrol module requires the following:

• Puppet Agent 4.7.1 or later.
• Access to the internet.
• Microsoft .NET 4.6.1 Runtime.
• Windows Server 2012/2012R2/2016.

Beginning with nservicebusservicecontrol

To get started with the nservicebusservicecontrol module simply include the following in your manifest:

include nservicebusservicecontrol

This example downloads, installs, and configures the latest version of servicecontrol. After running this you should be able to begin to create service control instances and perform other tasks using the nservicebusservicecontrol::instance defined type.

NOTE: By default this module pulls the package from chocolatey (https://chocolatey.org/packages/servicecontrol)

Usage

All parameters for the nservicebusservicecontrol module are contained within the main nservicebusservicecontrol class, so for any function of the module, set the options you want. See the common usages below for examples.

Install a specific version of service control from chocolatey

class { 'nservicebusservicecontrol':
  package_ensure     => '3.6.2',
}

NOTE: We recommend always specifying a specific version so that it's easily viewable and explicit in code. The default value is present which just grabs whatever version happens to be the latest at the time your first puppet run happened with this code

Automatically install newer versions as they are released on chocolatey

class { 'nservicebusservicecontrol':
  package_ensure     => 'latest',
}

NOTE: Use this with caution. New versions could contain a bug and since servicecontrol sometimes performs migrations on upgrades it's impossible to downgrade without going through the hassle of uninstalling and reinstalling the package

Install your license

$license_xml = @(LICENSE)
<?xml version="1.0" encoding="utf-8"?>
<license type="Commercial" DeploymentType="Elastic Cloud" Quantity="4" Edition="Enterprise" Applications="All" RenewalType="Subscription" expiration="2020-01-23" Notes="BlueSnap" id="7d26ad59-8805-4da6-8dad-f3540213ca">
...
</license>
LICENSE

class { 'nservicebusservicecontrol':
  package_ensure     => 'present',
  license_xml        => $license_xml,
}

Service Control Instances

Create a Service Control Instance using the MSMQ Transport

nservicebusservicecontrol::instance { 'Particular.ServiceControl.Development':
  ensure    => 'present',
  transport => 'MSMQ',
}

NOTE: Ensure the MSMQ Windows Feature is is already installed. ServiceControl by default will take care of creating the tables for using as queues

Create a Service Control Instance using the RabbitMQ Conventional Routing Topology Transport

nservicebusservicecontrol::instance { 'Particular.ServiceControl.Development':
  ensure            => 'present',
  transport         => 'RabbitMQ - Conventional routing topology',
  connection_string => 'host=localhost;username=guest;password=guest',
}

Create a Service Control Instance using the SQLServer Transport ( SQL Authentication )

nservicebusservicecontrol::instance { 'Particular.ServiceControl.Development':
  ensure            => 'present',
  transport         => 'SQL Server',
  connection_string => 'Data Source=.; Database=Particular.ServiceControl.Development; User Id=svc-servicecontrol; Password=super-secret-password;',
}

NOTE: Ensure the database is already created and the user can connect. ServiceControl by default will take care of creating the tables for using as queues.

Create a Service Control Instance using the SQLServer Transport ( Windows Authentication )

nservicebusservicecontrol::instance { 'Particular.ServiceControl.Development':
  ensure                   => 'present',
  transport                => 'SQL Server',
  connection_string        => 'Data Source=.; Database=Particular.ServiceControl.Development; Trusted_Connection=True;',
  service_account          => 'DOMAIN\svc-servicecontrol',
  service_account_password => 'super-secret-password',
}

NOTE: Ensure the database is already created and the user can connect. ServiceControl by default will take care of creating the tables for using as queues.

Create a Service Control Instance using the Azure Storage Queue Transport

nservicebusservicecontrol::instance { 'Particular.ServiceControl.Development':
  ensure            => 'present',
  transport         => 'Azure Storage Queue',
  # connection_string => 'UseDevelopmentStorage=true',
  connection_string => 'DefaultEndpointsProtocol=https;AccountName=[ACCOUNT];AccountKey=[KEY];',
  ...
}

Create a Service Control Instance using the Azure Service Bus Transport

nservicebusservicecontrol::instance { 'Particular.ServiceControl.Development':
  ensure            => 'present',
  transport         => 'Azure Service Bus',
  connection_string => 'Endpoint=sb://[NAMESPACE].servicebus.windows.net/;SharedAccessKeyName=[KEYNAME];SharedAccessKey=[KEY]',
  ...
}

Create a Service Control Instance using the Amazon SQS Transport

nservicebusservicecontrol::instance { 'Particular.ServiceControl.Development':
  ensure    => 'present',
  transport => 'AmazonSQS',
  ...
}

Service Control Instance with forward error & audit queues

nservicebusservicecontrol::instance { 'Particular.ServiceControl.Development':
  ensure                 => 'present',
  transport              => 'RabbitMQ',
  connection_string      => 'host=localhost;username=guest;password=guest',
  forward_audit_messages => true,
  audit_log_queue        => 'audit.log',
  forward_error_messages => true,
  error_log_queue        => 'error.log',
}

NOTE: If external integration is not required, it is highly recommend to turn forwarding queues off. Otherwise, messages will accumulate unprocessed in the forwarding queue until eventually all available disk space is consume

Service Control Monitoring Instances

Create a Service Control Monitoring Instance using the MSMQ Transport

nservicebusservicecontrol::monitoring_instance { 'Particular.Monitoring.Development':
  ensure    => 'present',
  transport => 'MSMQ',
}

NOTE: Ensure the MSMQ Windows Feature is is already installed. ServiceControl by default will take care of creating the tables for using as queues

Create a Service Control Monitoring Instance using the RabbitMQ Conventional Routing Topology Transport

nservicebusservicecontrol::monitoring_instance { 'Particular.Monitoring.Development':
  ensure            => 'present',
  transport         => 'RabbitMQ - Conventional routing topology',
  connection_string => 'host=localhost;username=guest;password=guest',
}

Create a Service Control Monitoring Instance using the SQLServer Transport ( SQL Authentication )

nservicebusservicecontrol::monitoring_instance { 'Particular.Monitoring.Development':
  ensure            => 'present',
  transport         => 'SQL Server',
  connection_string => 'Data Source=.; Database=Particular.Monitoring.Development; User Id=svc-servicecontrol; Password=super-secret-password;',
}

NOTE: Ensure the database is already created and the user can connect. ServiceControl by default will take care of creating the tables for using as queues.

Create a Service Control Monitoring Instance using the SQLServer Transport ( Windows Authentication )

nservicebusservicecontrol::monitoring_instance { 'Particular.Monitoring.Development':
  ensure                   => 'present',
  transport                => 'SQL Server',
  connection_string        => 'Data Source=.; Database=Particular.Monitoring.Development; Trusted_Connection=True;',
  service_account          => 'DOMAIN\svc-servicecontrol',
  service_account_password => 'super-secret-password',
}

NOTE: Ensure the database is already created and the user can connect. ServiceControl by default will take care of creating the tables for using as queues.

Create a Service Control Monitoring Instance using the Azure Storage Queue Transport

nservicebusservicecontrol::monitoring_instance { 'Particular.Monitoring.Development':
  ensure            => 'present',
  transport         => 'Azure Storage Queue',
  # connection_string => 'UseDevelopmentStorage=true',
  connection_string => 'DefaultEndpointsProtocol=https;AccountName=[ACCOUNT];AccountKey=[KEY];',
  ..
}

Create a Service Control Instance using the Azure Service Bus Transport

nservicebusservicecontrol::monitoring_instance { 'Particular.Monitoring.Development':
  ensure            => 'present',
  transport         => 'Azure Service Bus',
  connection_string => 'Endpoint=sb://[NAMESPACE].servicebus.windows.net/;SharedAccessKeyName=[KEYNAME];SharedAccessKey=[KEY]',
  ...
}

Create a Service Control Instance using the Amazon SQS Transport

nservicebusservicecontrol::monitoring_instance { 'Particular.Monitoring.Development':
  ensure    => 'present',
  transport => 'AmazonSQS',
  ...
}

Reference

See REFERENCE.md

Limitations

Unable to detect failing to create servicecontrol instance

There is a bug in the New-ServiceControlInstance powershell cmdlet that ships with servicecontrol that causes any failure to not be propogated to the caller correctly. This makes it impossible to determine if the instance creation was successful or failed. Therefore, failed puppet runs could be misleading and the resulting errors might be caused from this situation.

https://github.com/Particular/ServiceControl/issues/1565

Upgrading of the package after initial install

Currently there is no implementation to handle upgrading the package after intiail install via this module. In the future it might be helpful to implement the ability to specify an internal chocolatey server the user can use as well as handle upgrades, if possible, when downloading the install file from the public internet.

Module is missing some Service Control Instance Configuration settings

Neither the Unattended file method or New-ServiceControlInstance powershell cmdlet ( which this modules uses ) cover all the many configuration settings that are available to a ServiceControl Instance. The only mechanism that can be used to utilize all of the available customizations is by specifying them in the "ServiceControl.exe.config" file that resides in the service control instances install directory. If you would like to be able to configure one of these please open up a Github issue.

All documented available settings ( https://docs.particular.net/servicecontrol/creating-config-file )

Forwarding queues are created only at servicecontrol instance creation time only

If you try and a forwarding queue ( error or audit ) after a service control instance is created these queues will not get created. It's therefore your responsibility to manually create these and set them up if you decide to change your mind after a servicecontrol instance has been created. This is a limitation of servicecontrol itself.

Unsupported transports

I have selectively chosen not to support what appears to be old or deprecated transports. If you need one feel free to open an issue and if your feeling lucky submitting a pull-request.

• Azure Service Bus - Forwarding topology (Legacy)
• Azure Service Bus - Forwarding topology (Old)
• Azure Service Bus - Endpoint-oriented topology (Legacy)
• Azure Service Bus - Endpoint-oriented topology (Old)
• RabbitMQ - Direct routing topology (Old)

Contributing

1. Fork it ( https://github.com/tragiccode/tragiccode-nservicebusservicecontrol/fork )
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create a new Pull Request

Reference

Table of Contents

Classes

Public Classes

• nservicebusservicecontrol: Installs and configures Particular's Service Control Monitoring Tool.

Private Classes

• nservicebusservicecontrol::config: This class handles the configuration of servicecontrol.
• nservicebusservicecontrol::install: This class handles the management of the servicecontrol installer and package.

Defined types

• nservicebusservicecontrol::instance: Manages Service Control Instances.
• nservicebusservicecontrol::monitoring_instance: Manages Service Control Monitoring Instances.

Classes

nservicebusservicecontrol

Installs and configures Particular's Service Control Monitoring Tool.

Parameters

The following parameters are available in the nservicebusservicecontrol class.

package_ensure

Data type: String

Whether to install the ServiceControl package.

Default value: 'present'

package_source

Data type: Optional[String]

The package source for the package.

Default value: undef

license_xml

Data type: Optional[String]

A valid NServiceBus XML License.

Default value: ''

Defined types

nservicebusservicecontrol::instance

Manages Service Control Instances.

Parameters

The following parameters are available in the nservicebusservicecontrol::instance defined type.

ensure

Data type: Enum['present', 'absent']

Specifies whether the instance should exist.

instance_name

Data type: String

Specify the name of the ServiceControl Instance (title).

Default value: $title

install_path

Data type: Stdlib::Absolutepath

Specify the directory to use for this ServiceControl Instance.

Default value: "C:\Program Files (x86)\Particular Software\${instance_name}"

db_path

Data type: Stdlib::Absolutepath

Specify the directory that will contain the nservicebusservicecontrol database for this ServiceControl Instance.

Default value: "C:\ProgramData\Particular\ServiceControl\${instance_name}\DB"

db_index_storage_path

Data type: Stdlib::Absolutepath

Specify the path for the indexes on disk.

Default value: "${db_path}\Indexes"

db_logs_path

Data type: Stdlib::Absolutepath

Specify the path for the Esent logs on disk.

Default value: "${db_path}\logs"

log_path

Data type: Stdlib::Absolutepath

Specify the directory to use for this ServiceControl Logs.

Default value: "C:\ProgramData\Particular\ServiceControl\${instance_name}\Logs"

instance_log_level

Data type: Nservicebusservicecontrol::Log_level

Specify the level of logging that should be used in ServiceControl logs.

Default value: 'Warn'

host_name

Data type: Stdlib::Fqdn

Specify the hostname to use in the URLACL.

Default value: 'localhost'

port

Data type: Stdlib::Port

Specify the port number to listen on. If this is the only ServiceControl instance then 33333 is recommended.

Default value: 33333

database_maintenance_port

Data type: Stdlib::Port

Specify the database maintenance port number to listen on. If this is the only ServiceControl instance then 33334 is recommended.

Default value: 33334

expose_ravendb

Data type: Boolean

Specify if the embedded ravendb database should be accessible outside of maintenance mode.

Default value: false

ravendb_log_level

Data type: Nservicebusservicecontrol::Log_level

Specify the level of logging that should be used in ravendb logs.

Default value: 'Warn'

error_queue

Data type: String

Specify ErrorQueue name to consume messages from.

Default value: 'error'

audit_queue

Data type: String

Specify AuditQueue name to consume messages from.

Default value: 'audit'

error_log_queue

Data type: Optional[String]

Specify Queue name to forward error messages to.

Default value: 'error.log'

audit_log_queue

Data type: Optional[String]

Specify Queue name to forward eudit messages to.

Default value: 'audit.log'

transport

Data type: Nservicebusservicecontrol::Transport

Specify the NServiceBus Transport to use.

Default value: 'MSMQ'

display_name

Data type: String

Specify the Windows Service Display name. If unspecified the instance name will be used.

Default value: $instance_name

connection_string

Data type: Optional[String]

Specify the connection string to use to connect to the queuing system.

Default value: undef

description

Data type: String

Specify the description to use on the Windows Service for this instance.

Default value: 'A ServiceControl Instance'

forward_audit_messages

Data type: Boolean

Specify if audit messages are forwarded to the queue specified by AuditLogQueue.

Default value: true

forward_error_messages

Data type: Boolean

Specify if audit messages are forwarded to the queue specified by ErrorLogQueue.

Default value: false

service_account

Data type: String

The Account to run the Windows service.

Default value: 'LocalSystem'

service_account_password

Data type: Optional[String]

The password for the ServiceAccount.

Default value: undef

service_restart_on_config_change

Data type: Boolean

Specify if the servicecontrol instance's windows service should be restarted to pick up changes to its configuration file.

Default value: true

audit_retention_period

Data type: String

Specify the period to keep an audit message before it is deleted.

Default value: '30.00:00:00'

error_retention_period

Data type: String

Specify thd grace period that faulted messages are kept before they are deleted.

Default value: '15.00:00:00'

event_retention_period

Data type: String

Specifies the period to keep event logs before they are deleted.

Default value: '14.00:00:00'

expiration_process_timer_in_seconds

Data type: Integer

Specifies the number of seconds to wait between checking for expired messages.

Default value: 600

expiration_process_batch_size

Data type: Integer

Specifies the batch size to use when checking for expired messages.

Default value: 65512

hours_to_keep_messages_before_expiring

Data type: Integer

Specifies the number of hours to keep a message before it is deleted.

Default value: 720

maximum_message_throughput_per_second

Data type: Integer

Specifies the maximum throughput of messages ServiceControl will handle per second and is necessary to avoid overloading the underlying messages database.

Default value: 350

max_body_size_to_store

Data type: Integer

Specifies the upper limit on body size to be configured.

Default value: 102400

http_default_connection_limit

Data type: Integer

Specifies the maximum number of concurrent connections allowed by ServiceControl.

Default value: 100

heartbeat_grace_period

Data type: String

Specifies the period that defines whether an endpoint is considered alive or not since the last received heartbeat.

Default value: '00:00:40'

service_manage

Data type: Boolean

Specifies whether or not to manage the desired state of the windows service for this instance.

Default value: true

skip_queue_creation

Data type: Boolean

Normally an instance will attempt to create the queues that it uses. If this flag is set, queue creation will be skipped.

Default value: false

automatic_instance_upgrades

Data type: Boolean

Automatically upgrade the service control monitoring instance when a new version of servicecontrol is installed.

Default value: true

remove_db_on_delete

Data type: Boolean

Default value: false

remove_logs_on_delete

Data type: Boolean

Default value: false

nservicebusservicecontrol::monitoring_instance

Manages Service Control Monitoring Instances.

Parameters

The following parameters are available in the nservicebusservicecontrol::monitoring_instance defined type.

ensure

Data type: Enum['present', 'absent']

Specifies whether the monitoring instance should exist.

instance_name

Data type: String

Specify the name of the ServiceControl Monitoring Instance (title).

Default value: $title

install_path

Data type: Stdlib::Absolutepath

Specify the directory to use for this ServiceControl Monitoring Instance.

Default value: "C:\Program Files (x86)\Particular Software\${instance_name}"

log_path

Data type: Stdlib::Absolutepath

Specify the directory to use for this ServiceControl Monitoring Logs.

Default value: "C:\ProgramData\Particular\ServiceControl\${instance_name}\Logs"

instance_log_level

Data type: Nservicebusservicecontrol::Log_level

Specify the level of logging that should be used in ServiceControl Monitoring logs.

Default value: 'Warn'

host_name

Data type: Stdlib::Fqdn

Specify the hostname to use in the URLACL.

Default value: 'localhost'

port

Data type: Stdlib::Port

Specify the port number to listen on. If this is the only ServiceControl Monitoring instance then 33633 is recommended.

Default value: 33633

error_queue

Data type: String

Specify the ErrorQueue name.

Default value: 'error'

transport

Data type: Nservicebusservicecontrol::Transport

Specify the NServiceBus Transport to use.

Default value: 'MSMQ'

display_name

Data type: String

Specify the Windows Service Display name. If unspecified the monitoring instance name will be used.

Default value: $instance_name

connection_string

Data type: Optional[String]

Specify the connection string to use to connect to the queuing system.

Default value: undef

description

Data type: String

Specify the description to use on the Windows Service for this instance.

Default value: 'A Monitoring Instance'

service_account

Data type: String

The Account to run the Windows service.

Default value: 'LocalSystem'

service_account_password

Data type: Optional[String]

The password for the ServiceAccount.

Default value: undef

service_restart_on_config_change

Data type: Boolean

Specify if the servicecontrol monitoring instance's windows service should be restarted to pick up changes to its configuration file.

Default value: true

service_manage

Data type: Boolean

Specifies whether or not to manage the desired state of the windows service for this instance.

Default value: true

skip_queue_creation

Data type: Boolean

Normally an instance will attempt to create the queues that it uses. If this flag is set, queue creation will be skipped.

Default value: false

remove_logs_on_delete

Data type: Boolean

Specifies if the service control logs should be deleted with the instance.

Default value: false

automatic_instance_upgrades

Data type: Boolean

Automatically upgrade the service control monitoring instance when a new version of servicecontrol is installed.

Default value: true

Change log

All notable changes to this project will be documented in this file. The format is based on Keep a Changelog and this project adheres to Semantic Versioning.

0.3.0 (2019-02-04)

Full Changelog

Added

• (GH-6) Ability to manage service control monitoring instances #8 (TraGicCode)

0.2.1 (2019-01-25)

Full Changelog

Fixed

• Fixing up dependency conflict with chocolatey. #5 (TraGicCode)

0.2.0 (2019-01-25)

Full Changelog

Added

• Use chocolatey for the servicecontrol package. #3 (TraGicCode)

0.1.0 (2019-01-24)

Full Changelog

* This Changelog was automatically generated by github_changelog_generator