Prerequisites
These instructions assume the following:
- ServiceControl has been installed and is listening on
http:/
./ localhost:33333/ api - A ServiceControl Monitoring instance has been installed and is listening on
http:/
./ localhost:33633 - ServicePulse has been installed.
Basic setup
Steps
- Create a directory for the ServicePulse files
- Extract the ServicePulse files
- Disable/Remove ServicePulse
- Remove the
netsh
url restriction - Make sure that WebSocket support is enabled for IIS
- Create a website in IIS referring to the ServicePulse directory
- Configure URL Rewrites
Detailed steps
By default, ServicePulse is installed as a Windows Service that will self-host the ServicePulse web application.
It is possible to manually install ServicePulse using IIS following these steps:
- Extract the ServicePulse files using the following command at a command prompt:
ServicePulse.Host.exe --extract --outPath="C:\inetpub\websites\ServicePulse"
ServicePulse.Host.exe
can be found in the ServicePulse installation directory. The default location for this directory is %programfiles(x86)%\Particular Software\ServicePulse
Once the ServicePulse files are successfully extracted, configure a new IIS website whose physical path points to the location where the files have been extracted. Configure it to use port
9090
.When using IIS to host ServicePulse, the ServicePulse.Host service is not used. To remove the service, uninstall ServicePulse using Add/Remove Programs.
Use the following command on an elevated command prompt to remove the URLACL that was created by the ServicePulse installer to use port 9090 without any restrictions.
netsh http delete urlacl http://+:9090/
- Install the URL Rewrite module, then in the root directory of the IIS website, create a
web.
file with the following content:config
<?xml version="1.0" encoding="UTF-8"?>
<configuration>
<system.webServer>
<rewrite>
<rules>
<rule name="Handle app.constants.js requests from AngularJs" stopProcessing="true">
<match url="^a/js/app.constants.js(.*)" />
<action type="Rewrite" url="/js/app.constants.js{R:1}" />
</rule>
<rule name="Handle Vue.js routing paths" stopProcessing="true">
<match url="(.*)" />
<conditions logicalGrouping="MatchAll">
<add input="{REQUEST_FILENAME}" matchType="IsFile" negate="true" />
<add input="{REQUEST_FILENAME}" matchType="IsDirectory" negate="true" />
</conditions>
<action type="Rewrite" url="/" />
</rule>
</rules>
</rewrite>
</system.webServer>
</configuration>
Hosting ServicePulse within a subfolder
It is possible to host ServicePulse within a subfolder, but this requires changes to the configuration. The first change is that the URL Rewrite configuration must be aware of the subfolder. The rewrite must include the SubFolder name in both the match as well as the rewrite action.
<?xml version="1.0" encoding="UTF-8"?>
<configuration>
<system.webServer>
<rewrite>
<rules>
<rule name="Handle app.constants.js requests from AngularJs" stopProcessing="true">
<match url="^SubFolder/a/js/app.constants.js(.*)" />
<action type="Rewrite" url="/SubFolder/js/app.constants.js{R:1}" />
</rule>
<rule name="Handle Vue.js routing paths" stopProcessing="true">
<match url="(.*)" />
<conditions logicalGrouping="MatchAll">
<add input="{REQUEST_FILENAME}" matchType="IsFile" negate="true" />
<add input="{REQUEST_FILENAME}" matchType="IsDirectory" negate="true" />
</conditions>
<action type="Rewrite" url="/" />
</rule>
</rules>
</rewrite>
</system.webServer>
</configuration>
The second required configuration change is to specify the name of the subfolder in the base_url
. This is done by:
- Go to the root directory for the website created in the basic configuration.
- Edit
js\
file and set theapp. constants. js base_url
variable to be the name of the subfolder.
base_url
variable must have a /
character both before and after the name of the subfolder. E.g. /SubFolder
.e.g.
window.defaultConfig = {
default_route: '/dashboard',
base_url: '/SubFolder/',
version: '1.34.0',
service_control_url: 'http://localhost:33333/api/',
monitoring_urls: [''],
showPendingRetry: false
};
Advanced configuration
ServicePulse relies on the ServiceControl and ServiceControl Monitoring REST APIs. Both can be exposed. It is possible to add a reverse proxy to the ServicePulse website using the Microsoft URL Rewrite IIS extension.
ServiceControl
localhost
then change the hostname value back to localhost
.Installation steps:
- Install IIS URL Rewrite extension.
- Go to the root directory for the website created in the basic configuration.
- Edit
js\
and change theapp. constants. js serviceControlUrl
value fromhttp:/
to/ localhost:33333/ api api/
. - Open the IIS management tool.
- Select the root directory from within the IIS management tool.
- Open or create a
web.
fileconfig - Add the following rewrite rules to the top of the file:
<?xml version="1.0" encoding="UTF-8"?>
<configuration>
<system.webServer>
<rewrite>
<rules>
<rule name="Rewrite main instance API URL" stopProcessing="true">
<match url="^api/(.*)" />
<action type="Rewrite" url="http://localhost:33333/api/{R:1}" />
</rule>
<rule name="Legacy rewrite main instance API URL" stopProcessing="true">
<match url="^a/api(.*)" />
<action type="Rewrite" url="http://localhost:33333/api/{R:1}" />
</rule>
</rules>
</rewrite>
</system.webServer>
</configuration>
It is also recommended that the IIS website be configured to use TLS if an authorization provider is used.
Configuring SignalR rewrite rules
Due to a bug in SignalR in Microsoft.AspNet.SignalR.JS version 2.2.0, usage of IIS as a reverse proxy requires an additional URL Rewrite Rule. This rule should look as follows:
<?xml version="1.0" encoding="UTF-8"?>
<configuration>
<system.webServer>
<rewrite>
<outboundRules>
<rule name="Update URL property" preCondition="JSON" enabled="true" stopProcessing="true">
<match filterByTags="None" pattern="\"Url\":\"(.+?)\"" />
<conditions>
<add input="{URL}" pattern="(.*)/api/" />
</conditions>
<action type="Rewrite" value=""Url":"{C:1}{R:1}"" />
</rule>
<preConditions>
<preCondition name="JSON">
<add input="{URL}" pattern="/api/messagestream/negotiate" />
<add input="{RESPONSE_CONTENT_TYPE}" pattern="application/json" />
</preCondition>
</preConditions>
</outboundRules>
</rewrite>
</system.webServer>
</configuration>
ServiceControl monitoring
When using monitoring capabilities the following steps should be followed to create a reverse proxy to access the monitoring API from IIS.
Installation steps:
- Install the IIS Application Request Routing extension.
- Go to the root directory for the website created in the basic configuration.
- Edit
js\
and change theapp. constants. js monitoring_urls
value fromhttp:/
to/ localhost:33633/ monitoring/
. - Open the IIS management tool.
- Select the root directory from within the IIS management tool.
- Open or create a
web.
fileconfig - Add the following rewrite rules to the top of the file:
<?xml version="1.0" encoding="UTF-8"?>
<configuration>
<system.webServer>
<rewrite>
<rules>
<rule name="Rewrite monitoring API URL" stopProcessing="true">
<match url="^monitoring/(.*)" />
<action type="Rewrite" url="http://localhost:33633/{R:1}" />
</rule>
<rule name="Legacy rewrite monitoring API URL" stopProcessing="true">
<match url="^a/monitoring/(.*)" />
<action type="Rewrite" url="http://localhost:33633/{R:1}" />
</rule>
</rules>
</rewrite>
</system.webServer>
</configuration>
Role-based security
After executing the steps outlined above, ServicePulse requires authentication before accessing any functionality.
However, once authenticated, authorization rules are not checked, so users have access to all functionality. To restrict access to specific features, use the IIS URL Authorization
feature. The following snippet can be placed in the web.
file in the root of the website to restrict access based on roles:
<system.webServer>
<security>
<authorization>
<remove users="*" roles="" verbs="" />
<add accessType="Allow" roles="SPReaders" verbs="GET,HEAD" />
</authorization>
</security>
</system.webServer>
<location path="api/errors">
<system.webServer>
<security>
<authorization>
<add accessType="Allow" roles="SPFailedMessages" verbs="POST,PATCH"/>
</authorization>
</security>
</system.webServer>
</location>
<location path="api/recoverability">
<system.webServer>
<security>
<authorization>
<add accessType="Allow" roles="SPFailedMessages" verbs="POST,PATCH,DELETE"/>
</authorization>
</security>
</system.webServer>
</location>
<location path="api/redirects">
<system.webServer>
<security>
<authorization>
<add accessType="Allow" roles="SPFailedMessages" verbs="POST,PUT,DELETE"/>
</authorization>
</security>
</system.webServer>
</location>
<location path="api/pendingretries">
<system.webServer>
<security>
<authorization>
<add accessType="Allow" roles="SPFailedMessages" verbs="POST,PATCH"/>
</authorization>
</security>
</system.webServer>
</location>
<location path="api/endpoints">
<system.webServer>
<security>
<authorization>
<add accessType="Allow" roles="SPMonitoring" verbs="PATCH,OPTIONS"/>
</authorization>
</security>
</system.webServer>
</location>
<location path="api/customchecks">
<system.webServer>
<security>
<authorization>
<add accessType="Allow" roles="SPMonitoring" verbs="DELETE"/>
</authorization>
</security>
</system.webServer>
</location>
<location path="api/messagestream">
<system.webServer>
<security>
<authorization>
<add accessType="Allow" users="?"/>
</authorization>
</security>
</system.webServer>
</location>
<location path="monitoring">
<system.webServer>
<security>
<authorization>
<add accessType="Allow" roles="SPMonitoring" verbs="OPTIONS"/>
</authorization>
</security>
</system.webServer>
</location>
There are three roles defined:
SPReaders
: members can read all content but cannot trigger any actions.SPFailedMessages
: members can manage failed messages (retry, delete, groups etc.).SPMonitoring
: members can manage monitoring (e.g. enabling/disabling heartbeat monitoring for a particular endpoint).
Limitations
If ServiceControl is secured with an authentication module other that Windows authentication, ServiceInsight will not be able to connect to the REST API exposed via IIS. ServiceInsight version 1.4 or greater is required to use Windows authentication.
Older versions of ServiceInsight can still be used locally, bypassing the security by connecting to the ServiceControl port directly using the http:/
URL.
Upgrading ServicePulse hosted in IIS
When ServicePulse is hosted in IIS, the upgrade process is as follows:
- Go to the root directory of the IIS website.
- View and record the current ServicePulse configuration, specifically the value of
serviceControlUrl
. For versions 1.3 and below, this parameter is set inconfig.
. Between versions 1.3 and 1.31.0, it is set injs app\
. For versions 1.31.1 and above, it is set injs\ app. constants. js js\
.app. constants. js - Remove everything from the root folder.
- Install the new version of ServicePulse using the standard instructions.
- Extract the files from the
ServicePulse.
using the following command, but replaceHost. exe
with the value saved from Step 2, and<recordedvalue>
with the path to the root directory of the IIS website.<webroot>
ServicePulse.Host.exe --extract --serviceControlUrl="<recordedvalue>" --outPath="<webroot>"
- Optionally, remove or disable the unneeded Windows service by uninstalling ServicePulse via Add/Remove Programs.
- The installer will add the URLACL which could restrict access and will need to be removed as described in the basic steps above.
Adding MIME types for web fonts
If 404 errors occur when serving webfonts, it is possible the MIME type for web fonts have not been configured. Add the following MIME type declarations via IIS Manager (HTTP Headers tab of website properties):
Extension | Mime Type |
---|---|
.eot | application/vnd.ms-fontobject |
.ttf | application/octet-stream |
.svg | image/svg+xml |
.woff | application/font-woff |
.woff2 | application/font-woff2 |