Configure PI Trusts for the Interface Node

Once you establish that you can connect with apisnap.exe and AboutPI-SDK.exe, you must configure PI Trusts for the interface node. An interface that connects without a PI Trust is granted “world” access rights or no access rights depending on the DefaultUserAccess timeout parameter. Since world access rights are read only by default, an interface that sends data to PI without being granted a PI Trust will generate the following message in the interface log on the Interface Node.

5.3 - Basic Interface Node Configuration

[-10401] No Write Access - Secure Object

Connect with apisnap.exe from the Interface Node to the PI Server node. You will see messages similar to the following in the PI Server Message Log on the PI Server Node:

New Pinet 1 connection: snapE No Trust established for: apollo.osisoft.int|192.168.9.198|snapE using default login

and

Access Denied: [-10413] No trust relation for this request ID: 64. Address: 192.168.9.198. Host: apollo.osisoft.int. Name: snapE

The log messages tell us the following. The application name of the connection was snapE. The IP Address was 192.168.9.198. The host name was a fully-qualified host name

(apollo.osisoft.int). The exact application name, IP Address, and host name as displayed in the message log must be used when configuring PI Trusts. Note that that application name is snapE, not apisnap.exe. Also note that using apollo in the PI trust for the above connection would not work. The fully qualified name apollo.osisoft.int must be used.

Connect with AboutPI-SDK.exe from the Interface Node. You will a message similar to the following.

Trust request from: OSI\MATZEN|apollo|192.168.9.198|AboutPI SDK.exe failed: [-10413] No trust relation for this request (110 ms)

Unlike the connection from apisnap, host name is apollo, not apollo.osisoft.int. This example illustrates that configuring trusts is sometimes experimental in nature. You must examine the credentials as displayed in the PI Message Log.

Below are basic guidelines for creating simple trusts for interface connections. For a comprehensive understanding of trusts and security, read the chapter Managing Security in the PI Server System Management Guide. The discussion below assumes that you are familiar with the information in that chapter.

Interface Trusts for PI API Connections

When configuring a trust for an API connection, do not specify the Windows Domain or the Windows Username because these credentials are not passed in the PI API connection credentials because PI API connections can come from UNIX and VMS nodes as well as Windows nodes. Trusts with these fields configured will not work for PI API connections. If you use the PI System Management Tools to configure a trust for a PI API application, then the trust configuration wizard will not let you specify these fields. That is, the wizard will prevent you from over specifying the PI API trust.

Although it is possible to use the application name in trusts for PI API applications, it is not part of the default recommendations. See the section Using the Application Name in Interface

Trusts if you are interested in using the application name in your trusts.

We recommend one of two options for configuring trusts from an API application. Option 1 involves configuring the following two trusts.

• One trust based on IP address and netmask

Option 2 provides slightly tighter security. Instead of configuring the above two trusts, set up the following trust.

• One trust based on IP address, netmask, and fully-qualified host name

In Option 2 if the IP address or fully-qualified host name changes, the trust will fail, whereas in Option 1, it will not fail.

Interfaces Trusts for PI API and PI SDK Connections

Check your interface-specific documentation to see if your interface requires PI-SDK connections in addition to PI API connections. We recommend configuring trusts in one of two ways for applications that require both connection types.

Option 1 involves setting up the following 3 trusts.

‰ One trust based on IP address and netmask. This trust works for both PI API and PI- SDK connections.

‰ One trust based on fully-qualified host name (i.e., apollo.osisoft.com). The PI API always uses the fully-qualified host name as opposed to an abbreviated form of the name.

‰ One trust based on the simple host name (i.e. apollo). The SDK typically uses the abbreviated simple host name. To verify the host name the PI-SDK will use, run

pidiag -host on the Interface Node.

With these 3 trusts established, the interface first attempts to connect by IP address. If the IP address changes, then a trust is granted based on the host name. Because the PI-SDK and PI API host name processing may differ, you should set up two trusts, one for each form of the host name.

Option 2 provides slightly tighter security. Set up just 2 trusts, one for the PI API and one for the SDK. In each trust, include host name, IP address, and netmask as qualifications for connection.

One trust based on IP address, netmask, and fully-qualified host (i.e., apollo.osisoft.com). This trust works for the PI API connection.

One trust based on IP address, netmask, and simple host name (i.e. apollo). This trust works for the PI-SDK connection. To verify the host name the PI-SDK will use, run pidiag -host

on the Interface Node.

Trusts for Interface Nodes with Multiple NICs

If your Interface node has multiple NICs, you must set up a trust for each IP address, even if you just see the connection with one. To see all IP addresses for a given computer, type

ipconfig -all at a command prompt.

Using the Application Name in Interface Trusts

Although it is possible to use the application name in trusts for PI API applications, the additional security gains is typically not warranted by the increase in complexity. Before adding complexity to your trusts be aware that interfaces is only as secure as the room the

5.3 - Basic Interface Node Configuration

interfaces are in. Interfaces are configured to allow writing data to the PI Server, so physical access to the machine allows any user who can log on to that machine to run PI applications that could write data to the PI Server and a malevolent user could use an application name for which a trust is already configured.

Part of the complexity arises when buffering is configured on the Interface Node because a PI Trust must be configured for the buffering application as well as the interface. For Windows and UNIX, the buffering application (bufserv.exe) has an application name of APIBE. For VMS, the buffering application has an application name of EXCP plus a 4-digit process identifier.

There is additional complexity for interfaces that connect with both the PI API and PI-SDK because the PI API and PI-SDK pass different Application Names in their connection credentials. For example, the OPC interface uses opciE for the API and opcint.exe for the SDK. The application name for PI API interface connections can be determined by examining connection messages in the PI Message Log on the server, whereas the PI-SDK uses the actual file name of the executable.