Server Configuration

Note

The Stream Connector is deprecated and we recommend using the MQTT connector for inter-task and inter-instance communications.

Internet Information Server

Some configuration is required if you plan to serve data to stream clients across the Intranet or Internet. If you plan to connect to stream servers elsewhere in client mode only then you do not need to configure a local stream server and you can skip this chapter.

The Stream Connector Bundle installs the “Microsoft .NET Core Hosting Bundle” onto the target machine to work in conjunction with Microsoft Internet Information Server (IIS) as the front end for stream server access. IIS is a Microsoft Windows component.

Important

If possible, activate IIS before installing the Stream Connector for Dataristix. If the Stream Connector Bundle is installed before IIS is activated then it is required to repair the “Microsoft .NET Core Hosting Bundle” after IIS activation. To repair, open the Windows Control Panel, goto “Programs and Features”, locate “Microsoft .NET Core 6.0.x - Windows Server Hosting”, right-click and select “Change” and “Repair”.

If this is the first time you install the Stream Connector or, more precisely, the Microsoft .NET Core Hosting Bundle, then a restart of IIS is required after installing the Stream Connector as described in the next section.

You can find more details about the the .NET Core Hosting bundle at https://docs.microsoft.com/en-us/aspnet/core/host-and-deploy/iis/?view=aspnetcore-6.0#install-the-net-core-hosting-bundle).

  • To activate IIS on desktop operating systems:
    • Open the control panel, click on “Programs” and then on “Turn Windows Features On or Off”.
    • Enable “Internet Information Services”.
    • Expand “World Wide Web Services” and ensure that “WebSocket Protocol” is ticked.
  • To activate IIS on server operating systems:
    • Open “Server Manager”.
    • In the dashboard view, under “Configure this local server”, click on “Add roles and features”.
    • Step through the dialog for the configuration of “Server Roles”.
    • Tick the “Web Server (IIS)” role; include management tools if prompted.
    • Move on to “Web Server (IIS)” and “Role Services” or expand “Web Server (IIS)” and “Web Server”, depending on the server operating system version.
    • Locate and expand “Application Development” and tick “WebSocket Protocol”.
    • Review features and complete the installation.

Activation steps may differ slightly depending on the operating system.

For detailed configuration options please see: https://docs.microsoft.com/en-us/aspnet/core/host-and-deploy/iis/?view=aspnetcore-6.0. For more information about IIS please visit the official IIS site at: https://www.iis.net/.

Restart IIS if required

If this is the first time that you have installed the Stream Connector or, more precisely, the Microsoft .NET Core Hosting Bundle, then a restart of IIS is required. After installing the Stream Connector, open an administrator command prompt and type:

net stop was /y
net start w3svc

This will restart the Windows Process Activation Service and the World Wide Web Publishing Service.

Stream Web Service

Open the IIS Management tool to configure the Stream Web service.

On desktop operating systems, type “IIS” in the start menu search field to launch “Internet Information Services (IIS) Manager”. If you cannot see IIS Manager listed in the start menu then look for it under “Administrative Tools”.

On server operating systems, open the “Server Manager” and select “Internet Information Services (IIS) Manager” from the “Tools” menu.

Add the Stream Web Service

Right click on “Sites” and select “Add Website” to add the Stream Web Service.

../_images/stream-iis-add-website.png

Enter the following information in the “Add Website” diaolog.

../_images/stream-iis-add-website-dlg.png

( 1 ) Enter a Web site name of your choosing.

( 2 ) Enter the physical path to the Stream Web Service. The default installation path for the Stream Web server is:

C:\Program Files\Rensen\Dataristix\Services\modules\Stream Connector\web

( 3 ) Select a protocol. In this example the “http” protocol is selected.

Warning

Use “http” for internal testing or secure environments only. Configure HTTPS for any publicly accessible stream service. While secret HMAC authentication keys are never transmitted in plain text, a secure connection is required to ensure data confidentiality.

( 4 ) Select a port where the Stream Web Service can be reached.

( 5 ) Enter a host name of your choice.

( 6 ) Click OK to add the new Web Site.

Note

If you would like to add the Dataristix Stream Service to an existing Website (for example, to make use of the same port) then right-click on the existing Website, select “Add Application”, and select the physical path as described in step 2 above. Configure a new application pool as described in the next section.

Configure the application pool

In the previous steps the “Dataristix Streams” application pool was added together with the Stream Service Web site. Click on “Application Pools” and double-click on “UA OfficeLink Streams” to configure the application pool and click “OK”.

../_images/stream-iis-select-application-pool.png

In the “Edit Application Pool” dialog change the “.NET CLR version” to “No managed code”.

../_images/stream-iis-config-application-pool.png

Test Web Service

The above example configures the Stream Web Service at: http://localhost:7272. Browse to the Web site and if everything is configured correctly then you should see a response similar to this one:

../_images/stream-iis-browse.png

After starting the Web site the Stream Web service may need a few seconds to initialize. If you see a blank page then you may need to retry after a little while. If you see an error page instead then you may need to repair the “Microsoft .NET Core Hosting Bundle” as outlined in the beginning of this chapter.

Note

You will not be able to browse to the Web page once you have configured access restrictions as described in the next chapter. Use the Dataristix application and configure streams instead to test connections.

Access Restrictions

Open the Dataristix application to restrict stream server access by configuring App IDs and secret keys that must be known by clients to gain access to the stream service. The stream server manages two key pairs for HMAC authentication which can be replaced independently.

../_images/stream-configuration.png

Both key pairs are valid but you should either instruct all clients to use the first or the second pair to allow for key rotation. For example, when all clients are using key pair #1 then renewing key pair #2 does not impact these clients. You can then instruct current clients to switch over to key pair #2. Once the last client has switched over to key pair #2, the first key pair is no longer needed and can be discarded (replaced). At that point in time clients that are no longer current but had access through key pair #1 will no longer be able to connect.

Important

Already established Websocket connections are not impacted by key replacement. Re-start the Stream Server Website using the IIS management tool to force a reconnection of authorized clients only.

Warning

Enable API key access restrictions for any public facing stream service.