Trusts for Interfaces

In order for an interface to be able to write data to the PI Server it must have the proper permissions.  Because the interface application cannot respond to a login prompt, we use the PI Trust table on the PI Server to map an interface connection to a specific user.  Below are guidelines for creating  trusts four your interfaces. 

A Simple Trust based on IP Address/Netmask only 

One of the simplest trusts you can make that works for any interface connection is one based upon IP Address and Netmask of the interface machine.  This works as long as you have static IP addresses.
 
The trust must be mapped to a user that has write access to all of the tags the interface uses on a PI Server. When using this type of trust, the PI Server will allow any application from that IP address to connect to the PI Server as the specified PI User, including interface tools, the Buffer Server, apisnap.exe, and PI System Management Tools, just to name a few.

The only information required to build this trust is the IP address assigned to the interface machine.  If the interface is running on the PI Server a trust is not required as the PI Server installs a trust for itself by default. To get the IP Address of the interface node, go to the interface machine and run the ipconfig command in a command prompt window and press Enter. Then build the trust on the PI Server based on the IP Address of the interface machine and a netmask value of 255. 255. 255. 255.

Use the PI System Manager Tools (PI SMT) Trust Editor plug-in to easily build a trust. Download the PI SMT 3 Install kit.

Cons of IP Address trusts: IP Addresses are not as user-friendly as host names, can be more easily spoofed, and are more likely to change over time. If you need to move or replace your interface box, it will be easier if you are using host name as a trust credential, rather than IP Address. If you have dynamically-assigned IP Addresses, then don't use IP Address in your trust table. 

Interface “Connection Types”
There are two different types of connection that can be made to the PI Server: The API and the SDK. At this time all OSI interfaces and the PI Buffer Server (BufServe.exe) use the PI API to connect to the PI Server. Some interfaces also use the SDK to connect, such as the OPC interface and the PI-to-PI Interface. The PI System Management Tools utility uses the SDK.  Distinguishing the type of connection may be important when creating trusts, especially if using host names or application names as part of the trust (see API vs. SDK connections below).

Trusts based on IP Address/Netmask and Host name
Often customers set up 2 trusts on an interface machine: One using the IP Address/Netmask, and one based on host name. This ensures that the interface will continue to send data if one trust fails (i.e., someone changes the IP Address). Note that the host name may be different depending on whether the interface uses the API or the SDK to connect.  See “How to determine the credentials for a trust” below for details on finding the IP address and host name credentials.

More Secure Trusts – Multiple Credentials
You can make a trust more secure by adding additional credentials to the trust.  For example, adding application name as a credential will only allow an application with that name to be trusted.  API and SDK connections pass application names differently as well (as described below).

More Secure Trusts – Specific Users
By default the Data Access group assigned to each tag is the piadmin group.  However, you can easily change this.  If you want to control access to tags, you can create a trusted PI User that has write-access to specific tags. You can do this by performing the following steps:

1. Create a PI User for the specific interface.
2. Create a PI Group for the specific interface.
3. Place the PI User in the new PI Group.
4. Assign the new PI Group to the datagroup attribute for each of the tags (you can use Tag Configurator to do this).
5. Change the dataaccess to g:rw.
6. Build a trust based on your new PI User.

You could skip the groups and just assign the PI User as the Owner of the tag(s), but using a PI Group preserves the creator of the tag(s) as the Owner.

API vs. SDK Connections

Application Names
The API and SDK transmit application names (AppName) differently and this must be taken into account when trusts are created.  With an application that uses the SDK for its connection, the entire application name is used.  With API-based applications, by default only the first four letters of the name and the capital letter “E” are presented.  At this point in time, there are no OSIsoft interfaces that use only the SDK for their connections (there are some that use both), however you may have SDK-based applications running on the interface node, such as PI SMT, ProcessBook, or DataLink, for which you will want to create a trust based on the appname. Let’s look at a fictional interface called the Automation interface.  If it were API-based it might appear to the server as “AutoE”, and if it were SDK-based it might appear as “automation.exe”.  The only way to know for certain is to follow the instructions below “How to determine the credentials for a trust.”

Host Names
Until PI SDK 1.3.4.333 was released, you often had to set up more than one trust when using host name in your trust credentials, because the API and SDK used different credentials when connecting to the PI Server. With PI SDK 1.3.4.333 and later, this is not longer the case.  You can use the Fully-Qualified Domain Name (FQDN) in your trust for both API and SDK connections.

All versions of the API use the fully-qualified host name. An example of a fully-qualified host name is "apollo.osisoft.com." The fully-qualified host name is obtained from a reverse-name lookup on the incoming IP address using DNS. If DNS is not available, it will look in the local Hosts file.  The SDK 1.3.3 and earlier will present to the server what is referred to as ‘simple host name’ or machine name. An example of this would be "apollo." PI SDK 1.3.4.333 and later presents both the simple and FQDN to the PI Server.

See “How to determine the credentials for a trust” below for details on finding the IP address and host name credentials.

PI Buffer Server
If you are using the PI Buffer Server on the interface node, it must have the same access rights as the interface.  If your PI Trust is based on host name or IP address, then the PI Buffer Server will connect; however, if your trusts are based on application, you must create an additional trust for the BufServ application. “APIBE” is the BufServ application name.

Trusts for Computers with Multiple NICs (Network Interface Cards)
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 from a given computer, type “ipconfig –all” at a command prompt.)

How to determine the credentials for a trust
These instructions apply to PI Server 3.3 and later. 

    To determine what credentials the API passes

1. Run a Command Prompt session.
2. Change to the pipc\bin\ directory.
3. Type the following command, substituting HostName with the host name of your PI Server, then press Enter:
   
             apisnap HostName
   
   
4. Look at the PI Server message log. You should see a message similar to the following:

0 pinetmgr 28-Jan-06 16:10:25 >> New Pinet 1 connection: snapE No Trust established for: apollo.osisoft.int|192.168.8.132|snapE using default login.

From this information, you can see the IP address (in this case 192.168.8.132 with NetMask of 255.255.255.255), application name “snapE” and host name “apollo.osisoft.int.”

If you see “Hostname: Unknown” instead of a computer name, the host name is not being resolved by the DNS. Another reason you may see "Unknown" is if you have intentionally disabled the "reversenamelookupflag" settings in your PI Timeout table.  You can check the status of this flag in the PI SMT3 Timeout Table Editor. A setting of '1'  means it's enabled; "0" is disabled. If Reverse-name lookup cannot be enabled in your environment, you can add a  hosts file on the local computer and add the fully-qualified name of the client to it to resolve this problem. Or don't use host name as a trust.

You can exit apisnap by pressing Enter when prompted for a tag name.

    To determine what credentials the SDK passes:

1. Open a command window on the client computer.
2. Change to the pipc\adm directory (this is where it is installed by default).
3. Type “pidiag -host” and press Enter.  You will see the following:
   
   C:\PI\adm>pidiag -host
   Domain   <OSI>
   Machine  <apollo>
   User     <jdoe>
   IP Addr  <192.168.13.22>
   FQDN     <apollo.osisoft.int> 
       ...plus additional information
   

• The Domain is name of your Domain.
• The Machine is the simple host name (i.e., "apollo"), which is the only host name passed by PI SDK 1.3.3 and earlier.
• The User is the Domain user name (not to be confused with the PI User).
• The IP Addr is the IP Address.
• The FQDN is included when running PI SDK 1.3.4 and later, and stands for the Fully-Qualified Domain Name, which is the same thing as fully-qualified host name (for example, "apollo.osisoft.int"). If using PI SDK 1.3.4 or later, you no longer have to use the simple host name in your trust connections. Fully-qualified host names are also required for PI Collectives.
  

Other ways to find trust credentials

• Start the interface and use the PI System Manager Tools (PI SMT 3.x) Network Manager Statistics plug-in to see what the interface connection is presenting (look at name, peername, peeraddress). This only works if the connection is successful.
  
• Run a remote 'pigetmsg' session to see the trust credentials being passed.The PI Server message logs shows attempted connections (successful or not) and their credentials:

0 pinetmgr 27-Feb-06 09:05:42
 >> Access Denied: [-10413] No trust relation for this request    ID: 36. Address:
192.168.8.176. Host: testbox.osisoft.int. Name: PIToE

    To run the remote pigetmsg session, do the following:

1. Run a Command Prompt session on the interface node.
2. Change to the pipc\adm\ directory.
3. Type the following command, and press Enter:

   pigetmsg -f -remote

4. Enter the appropriate login credentials when prompted.
5. Leave this window open to view the API and SDK connections as they occur.