How-to
Forward Canary historian data through a SaF proxy
Short answer
Forwarding site history to a corporate Canary historian is a Store and Forward routing job. Enable the Proxy feature in the sending SaF service, set RouteDestinations to localhost plus the corporate historian, and open TCP 55291 inbound on the destination. An API token with Write permission to the Historian View is required only when Tag Security is enabled on the destination Identity service.
On this page
- What the proxy actually is
- Decide whether you need a proxy at all
- Choose what runs the proxy
- Open the path on the SaF endpoint
- Enable the proxy and set the routes
- Handle identity and the API token
- Worked example: one site historian forwarding to one corporate historian
- Verify the forwarding path
- Questions asked
Forwarding a control-network historian to a corporate Canary historian is a Store and Forward (SaF) routing job, not a historian-to-historian replication. The old mirror function is discontinued; its replacement is the SaF proxy feature, documented for versions 24 and 25 as the configuration for a stream that must pass through an intermediate network level. Everything lives on the sending side: enable Proxy in the sending SaF service, set RouteDestinations to localhost plus the corporate historian, and open TCP 55291 inbound on the destination. The corporate historian needs no collectors and no pre-built tags, and an API token with Write permission to the Historian View is required only when Tag Security is enabled in its Identity service.
What the proxy actually is #
Any machine running a SaF service can pass data to the next hop instead of, or in addition to, handing it to a local historian. Collectors exist only at the start of the chain: once a collector hands its data to the local SaF service, SaF owns delivery to the next destination, whether that is an intermediate hop or a historian. The receiving side runs its own SaF service to accept the stream, so there is nothing to install or configure on the corporate historian beyond an open endpoint.
Tags are configured in the collector at the source and travel with the stream, so no tags are built on the destination. The proxy runs continuously and the site historian keeps its own full history the whole time, unlike a one-time project such as moving Wonderware Historian data into Canary Historian.
Decide whether you need a proxy at all #
Line of sight is the only deciding factor, so test it first.
- Check whether the collector's machine can open a connection to the corporate historian's SaF endpoint on TCP 55291 under the existing firewall rules.
- If it can, skip the proxy: in the collector user interface, list both destination historians in the destination field, separated by a comma. The collector's local SaF sends one stream to each.
- If it cannot — the collector sits on the control network and only the historian server may reach the business network — configure the proxy hop in the next sections.
Pick one path per data stream. If the collector already lists the corporate historian and the site SaF also forwards the same stream, the corporate historian records duplicate samples.
Choose what runs the proxy #
Both layouts below work; choose by what your firewall team will accept. A separate proxy is simply another host running the SaF service, such as a fanless mini PC mounted in the DMZ cabinet.
| Layout | Collector sends | Proxy SaF routes to | Cross-zone rules | Choose it when |
|---|---|---|---|---|
| Site historian is the proxy | One stream, to the site historian | localhost plus the corporate historian | 1 | The historian host is already the only machine allowed across the boundary, and you want one fewer server to patch |
| Separate proxy server | Two streams: the site historian and the proxy | The corporate historian only | 2 | Policy isolates the cross-zone connection from the historian host, for example a DMZ proxy |
Open the path on the SaF endpoint #
The receiving SaF service listens for inbound streams on its gRPC endpoint, TCP 55291, and data in transit on that endpoint is encrypted per the version 25 documentation. The sending SaF pushes to the next destination on 55291; its source port is assigned by the operating system, so write the rule on the destination port. The firewall work is one rule:
- Allow the proxy host to the corporate historian host, TCP 55291 inbound.
- Leave TCP 55290 closed. The version 23 endpoint list shows it as the anonymous SaF endpoint alongside the secure 55291, with only one endpoint serving the stream.
- Leave the API endpoints closed as well: the SaF service's web API on TCP 55293 and the HTTPS sender on TCP 55254 in the version 26 list serve API clients, not forwarding.
- Test from the proxy host before touching any SaF setting:
Test-NetConnection -ComputerName CorporateHistorian -Port 55291
Here CorporateHistorian stands for your corporate historian's host name. A failed test stops the chain regardless of any SaF configuration, so fix the path first. Under IEC 62443 this crossing is a conduit between a control zone and a business zone: one authorized path with named endpoints, not an open source range. For the wider boundary design, see plant network design for corporate versus manufacturing segmentation.
Enable the proxy and set the routes #
- In the Store and Forward tile of the sending SaF service, enable the Proxy feature.
- Read the current RouteDestinations value before changing anything.
- Write the route for your layout. Site historian as the proxy, storing locally and forwarding:
"RouteDestinations": [
{
"Destinations": [
{ "Endpoint": "localhost", "ForceHistorianConnection": false },
{ "Endpoint": "CorporateHistorian", "ForceHistorianConnection": false }
],
"RegexMatchKind": "SessionCollectorType",
"RegexMatchPattern": null
}
]
Separate proxy server, forwarding only:
"RouteDestinations": [
{
"Destinations": [
{ "Endpoint": "CorporateHistorian", "ForceHistorianConnection": false }
],
"RegexMatchKind": "SessionCollectorType",
"RegexMatchPattern": null
}
]
In both blocks, CorporateHistorian stands for the corporate historian's host name or address exactly as the proxy machine resolves it; localhost is literal. The localhost entry is what keeps the site historian fed — leave it out on the site historian and the site loses its own history. On a separate proxy server the collector must list two destinations, the site historian and the proxy, because the proxy stores nothing locally. Both blocks leave RegexMatchPattern as null with RegexMatchKind set to SessionCollectorType: use them as-is for a blanket forward, and add pattern matching only after the blanket route works.
Handle identity and the API token #
- Read the corporate historian's Identity settings for Tag Security.
- Tag Security off: no token is required. You are done with this section.
- Tag Security on: create the API token in the corporate Identity service — the one protecting the destination historian, not the site Identity service — with Write permission to the Historian View, and configure the forwarding SaF to present it.
- Two identity services on the two historians are not a conflict; the requirement is only that the SaF writing to each destination holds a token valid for that destination. Multiple SaF services can use the same token, so one token covers the proxy and any direct-sending collectors. If the proxy host is also remote from the site Identity service, create an internal Canary user on the site side and link it to the token generated in the corporate Identity service.
- The tooltip on the Identity API Token field in the SaF tile describes the token as used for remote historians, so the localhost route to the site historian is not expected to depend on it. Apply the change, then confirm the site historian keeps receiving before you walk away.
Worked example: one site historian forwarding to one corporate historian #
Inputs, each with its source:
- A collector and the site historian with its SaF service sit on the control network; the corporate historian is reached across a business-network port. This is the case that needs the proxy.
- The receiving SaF endpoint is TCP 55291 inbound, documented consistently from the version 23 endpoint list through the version 25 and 26 documentation.
- Tag Security is enabled on the corporate Identity service. If yours is off, the token step drops out and nothing else changes.
- Cost model: each SaF-to-SaF hop that crosses the zone boundary costs one firewall rule written on destination port 55291; the localhost hop and hops inside one zone cost none.
Rule in words: total cross-zone rules equals the number of SaF-to-SaF hops that cross the boundary.
Arithmetic:
- Site historian as the proxy: localhost (0 rules) plus site historian to corporate historian (1 rule) = 1 cross-zone rule, carried by one host.
- Separate DMZ proxy: collector to proxy (1 rule) plus proxy to corporate historian (1 rule) = 2 cross-zone rules on two hosts; the collector's stream to the site historian stays inside the control zone and adds 0.
- Difference: 2 − 1 = 1 rule and 1 host.
Result and decision: open exactly one inbound port, TCP 55291, with a single rule from the site historian host to the corporate historian host, and let the site historian act as the proxy. Commit to the separate proxy only when policy forbids the historian host from holding the cross-zone connection — and then it costs you exactly one more rule.
Verify the forwarding path #
- From the proxy host, the TCP check to the corporate historian on 55291 succeeds. If it fails, stop and fix the network before blaming SaF.
- The site historian keeps receiving new samples after the RouteDestinations change, which proves the localhost entry survived the edit.
- The corporate historian shows the site's tags with current timestamps, and each sample appears exactly once.
- While the path is down, the sending SaF buffers and drains on return, so bursts after an outage point at the network rather than the routing; the same buffer-and-drain design is what MQTT store and forward backfill after a connection outage relies on at the edge.
Questions asked
Does the corporate historian need collectors or tags built before it can receive proxied data?
No. Tags are configured in the collector at the source and their definitions travel with the stream. Collectors only exist at the start of the chain; after the handoff the Store and Forward service owns delivery. The receiving side needs nothing but its SaF endpoint open on TCP 55291, and a token only if Tag Security is enabled in Identity.
The endpoint list also shows TCP 55290 for the Store and Forward service. Should that be open too?
No. Open 55291 and leave 55290 closed. Documentation from version 23 lists 55290 as an anonymous SaF endpoint and 55291 as the secure one, with only one endpoint serving the stream, and later versions document 55291 as the encrypted gRPC endpoint. Web API clients use separate endpoints, such as the SaF web API on TCP 55293, and are not part of the forwarding path.
Can the two historians use different Identity services?
Yes, that arrangement is supported and is not a conflict. The only requirement is that each SaF writing to a destination holds a token valid for that destination. Create the API token in the corporate Identity service that protects the destination historian and give it Write permission to the Historian View. Multiple SaF services can share one token.
Will changing the API token on the site SaF disturb local storage on the site historian?
It is not expected to, because the localhost route should not depend on the token. Treat it as a point to verify: apply the change, confirm the site historian keeps receiving new samples, and only then call it done.
Why does the corporate historian receive data in bursts after an outage?
Because the sending SaF buffers locally while the network path is down and drains the buffer when the link returns. Bursts that follow outages point at an intermittent path, not at the routing configuration. Through the whole outage the site historian keeps logging normally through its localhost route.