The PI Trust Database is a table of trust records. Each record includes a unique name for the trust, a PI user name, and a combination of at least one of the following: Application Name, Domain name, IP address, Host, and Operating system user-name. Changes to the Trust Database take effect immediately. There is no need to restart any PI subsystem.
For more information about the Trust Database, see PI Server Reference Guide, Chapter 2,
PI Server Databases.
The following table shows whether each field is required or optional and whether it may be used for each type of connection credential.
Field in Trust Record Req or Opt. PI API PI SDK on Win98 PI SDK on WinNT or greater
Trust name req
AppName opt yes yes yes
Domain opt no no yes
IPAddr1 opt yes yes yes
Netmask opt yes yes yes
Host name opt yes yes yes
OSUser opt no no yes
PIUser req
6.9 - Trust Login Security
Before you configure records in the Trust Database, set up the entries in the User Database. For more information, see Adding a New PI User, page 127. When you establish a new trust record, if the PIUser you include does not already exist in the User Database, the trust record will be rejected.
Note: Trust record with only Trust name and PIUser are not allowed. Always include
at least one optional entry.
PI Server does not allow two trust records that differ only in PIUser, because this would create ambiguous trust login results.
Using Piconfig
Piconfig is the only tool that can modify the Trust Database. The key value of the Trust Database is Trust.
D:\PI\adm>piconfig
* (Ls - ) Piconfig> @tabl pitrust * (Ls - PITRUST) Piconfig> @?atr 1 - Trust String D: C: 2 - NEWTrust String D: C: 3 - AppName String D: C: 4 - Domain String D: C: 5 - IPAddr String D: C: 6 - IPHost String D: C: 7 - Netmask String D: C: 8 - OSUser String D: C: 9 - PIUser String D: C:
Suppose you wish to create a trust record that permits a PI-SDK application named
piperfmon.exe to connect as a User called Perfmon. You could name the trust record perfmondefault. Use the following commands to create the record above:
@table pitrust @mode create
@istru trust, appname, piuser
perfmondefault, piperfmon.exe, perfmon
Additional information about each field is given in the following sections.
Trust
The Trust field is required. It is a record name that must be unique within the Trust Table. Any alphanumeric combination is acceptable.
AppName
A blank value indicates the match is not required. Otherwise, a case-insensitive match is required.
For a PI API application to match the AppName, the AppName must be specified as the 4- character application name plus an “E” at the end.
For a PI-SDK application to match the AppName, the AppName must be specified as the filename of the application executable with file extension and without the directory path.
Domain
Windows Domain name may be used only for trust logins for PI-SDK client applications running on Windows operating systems. The domain must be the same for the PI Server and the connecting application.
A blank value indicates the match is not required. Otherwise, a case-insensitive match is required.
IPAddr and Netmask
The IPAddr and Netmask fields are optional and may be used for either PI API or PI-SDK applications. This pair of fields allows matching exact machine IP Addresses or specific subnets.
Setting both fields to 0.0.0.0 indicates that a match is not required. If these fields are left blank, PI Server will store 0.0.0.0 in both fields in the trust record.
If you specify IPAddr, you must also explicitly provide a Netmask value. Failure to do so will generate an error.
If you are requiring an exact match on an IP address, specify the Netmask as 255.255.255.255. If you are specifying a Class C subnet, specify the Netmask as 255.255.255.0 and the fourth field of the IPAddr as 0. Examples are given later in this chapter.
Note: The relationship between IPAddr and Netmask in the Trust Database is the
same as the relationship between Network Destination and Netmask in a TCP/IP routing table. The class C (24 bit) subnet is just an example—any valid subnet and
IPAddr is supported. If you use this mechanism to allow access to all addresses in a
subnet, you must set the bits corresponding to your subnet to zero.
IPHost
IPHost (sometimes called Host name or machine) is an optional field that may be used for either PI API or PI-SDK connections. It refers to the name of the connecting machine. Trust lookups based on IPHost are case-insensitive.
OSIsoft recommends that you verify the IPHost name as discussed below.
For PI API connections, the IPHost name is retrieved by PI Server using the IP address of the connecting client. The lookup generally requires access to a Domain Name Server (DNS). If a DNS is not used, the client IPHost name must be defined in the hosts table of the PI Server. To check this name, ping the client machine from the PI Server. For example, the DNS might provide JoePC.osisoft.com.
For PI-SDK connections, the IPHost name comes from the information sent by the client to the PI Server. This name is the short IPHost name. You can confirm this name by running
6.9 - Trust Login Security
For PI-SDK connections, PI Server verifies domain membership of a client computer by checking with a domain controller. If this field contains a dollar sign ($), it represents any machine within the domain.
In the example above, one trust record with an IPHost entry would not match both PI API and PI-SDK connection credentials.
OSUser
The OSUser (Operating system user) name field is used only for PI-SDK applications running within a Windows NT or Windows 2000 Domain.
Leaving this field blank indicates a match is not required. Otherwise a case-insensitive match is required.
Because Domain must be the same for both the PI Server and the connecting PI-SDK application, it is recommended that you include Domain whenever you want to include OSUser.
If this field contains a dollar sign ($), it represents any domain user. If the PIUser field in the trust record is also $, then the OSUser name must match a name in the PIUser database. If this field contains a dollar sign ($), and the PIUser field contains a specific PIUser, then all domain users will be granted the access rights of that PI user.
OSUser Names for Services on Windows
Interfaces that run as automatic Windows Services have a default OSUser name on the host machine. Unless overridden, this name is LocalSystem, which is not a Domain Username. If you wish to include OSUser name as part of a trust login, you must change the default name for the interface on the host machine to something that is defined in the Domain user
database.
User Manager in the Administrative Tools does not list the default LocalSystem name. Instead, follow these steps to set a new OSUser Name.
Windows NT:
1. Open Services in the Control Panel.
2. Select the interface service name and click Startup…. 3. In the dialog that appears, select Log on as This Account.
4. Type in a new User Name and Password (twice) or select a User Name from the dropdown list. Click OK.
Windows 2000/XP:
1. In the Control Panel, open Administrative Tools and then Services. 2. Select the interface service name and click Properties.
3. On the Properties page, select the Log On tab. 4. In the dialog that appears, select This Account.
5. Type in the Domain and a User Name and then a Password (twice) or select a User Name from the dropdown list. Click OK. In the example below, the Domain is “OSI” and the account User Name is piperfmon. The syntax is OSI\piperfmon.
Figure 6-1. Establishing PI Performance Monitor as a Windows Service PIUser
Required field. PIUser must be a valid user defined in the PI User Database (with one exception, described under OSUser). This field specifies the PI Server user whose privileges will be assigned to the incoming connection when the connection credentials match the specifications in the trust record.
Although you can choose the piadmin account for PIUser, it is preferable to reserve the use of piadmin for installation and management of the PI System.