Install ServicePulse in IIS

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

1. Create a directory for the ServicePulse files
2. Extract the ServicePulse files
3. Disable/Remove ServicePulse
4. Remove the netsh url restriction
5. Make sure that WebSocket support is enabled for IIS
6. Create a website in IIS referring to the ServicePulse directory
7. 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:

1. Extract the ServicePulse files using the following command at a command prompt:

ServicePulse.Host.exe --extract --outPath="C:\inetpub\websites\ServicePulse"

2. 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.

3. When using IIS to host ServicePulse, the ServicePulse.Host service is not used. To remove the service, uninstall ServicePulse using Add/Remove Programs.

4. 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/

5. Install the URL Rewrite module, then in the root directory of the IIS website, create a web.config file with the following content:

<?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:

1. Go to the root directory for the website created in the basic configuration.
2. Edit js\app.constants.js file and set the base_url variable to be the name of the 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

Installation steps:

1. Install IIS URL Rewrite extension.
2. Go to the root directory for the website created in the basic configuration.
3. Edit js\app.constants.js and change the serviceControlUrl value from http://localhost:33333/api to api/.
4. Open the IIS management tool.
5. Select the root directory from within the IIS management tool.
6. Open or create a web.config file
7. 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="\&quot;Url\&quot;:\&quot;(.+?)\&quot;" />
                    <conditions>
                        <add input="{URL}" pattern="(.*)/api/" />
                    </conditions>
                    <action type="Rewrite" value="&quot;Url&quot;:&quot;{C:1}{R:1}&quot;" />
                </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:

1. Install the IIS Application Request Routing extension.
2. Go to the root directory for the website created in the basic configuration.
3. Edit js\app.constants.js and change the monitoring_urls value from http://localhost:33633/ to monitoring/.
4. Open the IIS management tool.
5. Select the root directory from within the IIS management tool.
6. Open or create a web.config file
7. 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.config 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://localhost:33333/api URL.

Upgrading ServicePulse hosted in IIS

When ServicePulse is hosted in IIS, the upgrade process is as follows:

1. Go to the root directory of the IIS website.
2. View and record the current ServicePulse configuration, specifically the value of serviceControlUrl. For versions 1.3 and below, this parameter is set in config.js. Between versions 1.3 and 1.31.0, it is set in app\js\app.constants.js. For versions 1.31.1 and above, it is set in js\app.constants.js.
3. Remove everything from the root folder.
4. Install the new version of ServicePulse using the standard instructions.
5. Extract the files from the ServicePulse.Host.exe using the following command, but replace <recordedvalue> with the value saved from Step 2, and <webroot> with the path to the root directory of the IIS website.

ServicePulse.Host.exe --extract --serviceControlUrl="<recordedvalue>" --outPath="<webroot>"

1. Optionally, remove or disable the unneeded Windows service by uninstalling ServicePulse via Add/Remove Programs.
2. 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):