1.

Managing Security
The Advanced Historian data archive is typically used in production systems where correct and reliable operation is important. For this reason, a number of security mechanisms are available to protect against both willful and accidental tampering with the system. These include operating system security, physical security, network security, and several levels of security within the Advanced Historian. For information about network and operating system security, consult your system administrator and Windows NT online help. IMPORTANT: The Windows NT login account AdvHistUser is created when you install the Advanced Historian. Do not modify or delete this account. It is required for the Advanced Historian to function properly.

Securing the Physical Environment

Physical access to the Advanced Historian server should be restricted particularly if it is left unattended for long periods of time. We recommend that the server be located in a lockable, temperature-controlled computer room with an uninterruptible power supply (UPS), if possible.

Chapter 1. Managing Security

Securing the Advanced Historian

In addition to restricting physical access to the server, the Advanced Historian provides several forms of security including: Restricting access winth the Advanced Historian firewall. Creating users and groups accounts for Advanced Historian users. Assigning users to groups. Assigning an owner, a group, and access rights to the Point, User, and Digital State databases. Each database can have a different owner, group or access rights. Assigning an owner, a group, and access rights to each tag. Setting up the Proxy database to map API programs to a specific user account.

To complete these tasks, log into the Advanced Historian with the piadmin account.

Understanding Firewall Security

The first level of Advanced Historian security is a firewall maintained by the Network Manager, Pinetmgr. Pinetmgr manages all connections to the Advanced Historian server, including subsystem connections and TCP/IP applications. The utility also uses the Firewall database to screen access based on the IP address. If the address of a client requesting access is valid, Pinetmgr allows the client to connect. In this way, the Pinetmgr controls access to the data archive at the IP address level.

Using the Firewall Database

The Firewall database is a table with two fields. The first field is an IP address, IP address mask, or host name. IP address mask syntax consists of a portion of an IP address and asterisks. An asterisk in an IP address field matches any number.

Using the Advanced Historian

Examples
192.168.168.* 192.168.168.*

The second field defines the following keywords that instruct Pinetmgr whether or not it should complete the connection. ALLOW instructs Pinetmgr to complete the connection. DISALLOW instructs Pinetmgr to refuse the connection. When new connection request is received by Pinetmgr, the incoming host name and IP address are examined as follows: [1] If the request is from the computer on which Pinetmgr is running, the connection is automatically accepted. If the request is from a remote node (client), Pinetmgr searches the Firewall database for a matching IP address entry or host name entry. The search uses a wildcard compare. For example, the connecting address of 192.168.168.22 matches a address mask of 192.168.*.*. A matching DISALLOW has precedence over an ALLOW.

[2]

Example Address Mask 192.168.168.* 192.168.168.67 Value ALLOW DISALLOW

Using the table above, only hosts within the 192.168.168.0 subnet are allowed connections. However, the sepcific IP address 192.168.168.67 is not allowed to connect; even though it matches the first host mask. IMPORTANT: Adding an address mask of *.*.*.* and a value of DISALLOW to the Firewall database will prohibit all TCP/IP connections.

Chapter 1. Managing Security

Modifying the Firewall Database

You can modify the Firewall database using Piconfig, the configuration utility. To start Piconfig, enter the following text at the command line:
piconfig

Once your changes are made, the Advanced Historian recognizes them within 15 minutes or when you restart the server. You can only modify the Firewall database from the computer running Pinetmgr. Listing Attributes and Entries The name of the Firewall database is Pifirewall. You can open the Firewall database by entering the following text at the Piconfig prompt:
piconfig> @table pi_gen,pifirewall

To list the field attributes in the database, enter the bold text at the Piconfig prompt:
piconfig> @?atr 1 - hostmask 2 - value 3 = NEWhostmask

Notice that the name of the address mask field in the Firewall database is hostmask. This is also the primary key. To display all entries in the database, enter the following text at the Piconfig prompt:
piconfig> @ostructure hostmask,value (define format of data printed to screen) piconfig> @select hostmask=* (specify primary key to select) piconfig> @endsection (end of selection) *.*.*.* ALLOW

This listing shows the default firewall setting; all connections are allowed.

Granting Access to Connect

You can allow a connection from a specific subnet by entering the following text:
piconfig> @table pi_gen,pifirewall (open the database)

10

Using the Advanced Historian

piconfig> @mode create,t (put the database into create mode) piconfig> @istructure hostmask,value (define format of incoming data) piconfig> 192.168.168.*,ALLOW (enter mask and keyword)

Using Host and Domain Names in the Firewall Database

You can specify host names in the Firewall database by entering the host name and the domain name. For example, to prevent connections from host bobcat on domain nowhere.com, enter the following text:
piconfig> piconfig> piconfig> piconfig> @table pi_gen,pifirewall (open the database) @mode create (put the database into create mode) @istructure hostmask,value (define format of incoming data) bobcat.nowhere.com,DISALLOW (enter name and keyword)

Renaming an Existing Entry in the Firewall Database

The Firewall database provides the attribute NEWhostmask to let you rename an entry, as the following text shows:
piconfig> @table pi_gen,pifirewall (open the database) piconfig> @mode list (put the database into list mode) piconfig> @ostructure hostmask,value (define format of data printed to screen) piconfig> @select hostmask=* (specify primary key to select) 192.168.168.*,ALLOW bobcat.nowhere.com,DISALLOW piconfig> @mode edit (put the database into edit mode) piconfig> @istructure hostmask,NEWhostmask (define incoming data format) piconfig> bobcat.onwhere.com,tomcat.nowhere.com (enter old name and new

name) Once this change takes effect, connection attempts from tomcat are prohibited. Consequently, you ran the Apisnap utility from tomcat to examine the value of a point, you would see the following text as a result of the attempted connection:
e:\pi\adm>apisnap tamarind:5450 PI-API version 1.2.3.4 Attempting connection to tamarind:5450 Error 2, connecting to tamarind:5450

Likewise, the file PIPC.LOG on the host tomcat contains the following entry:
Chapter 1. Managing Security

11

11-Dec-99 16:19:03 D:\piapi\piapi32\apicomm.c> recv: Error: 10054, Unknown error

Examining the Advanced Historian servers message log also contains a message indicating the connection was not allowed:
0 pinetmgr 11-Dec-99 16:29:37 >> PInet Refused TCP/IP connection, hostname: tomcat.nowhere.com, 192.168.168.129

Modifying the Hostmask *.*.*.*.

You can modify the hostmask *.*.*.* by enclosing it in double quotation marks ( ). For example:
piconfig> @select hostmask=*.*.*.*

Understanding User Security

The Advanced Historian provides its own user security. When a user wants access to the Advanced Historian, he or she is prompted for a login name and password. Client applications (API programs) are responsible for prompting the user for this same information and then sending it to the Advanced Historian for authentication. IMPORTANT: The Windows NT login account AdvHistUser is created when you install the Advanced Historian. Do not modify or delete this account. It is required for the Advanced Historian to function properly.

Understanding the Group Database

Access to data or to point attributes is normally granted to groups of people, such as instrument engineers or operators, rather than to individuals. You can define a group account using Group database, Pigroup. Once a group is defined, you can assign membership to the group account using individual user accounts.

12

Using the Advanced Historian

The Group database contains the following fields. The primary key for the database is the Group field. Table 1-1: Group Database Fields Field Name Group User Description Contains... The name of the account. The users assigned to this group. Text describing the account.

Understanding the User Database

You can create user accounts for the Advanced Historian using the User database, Piuser. You can assign a user account to any number of group accounts. The User database also stores user passwords. However, to change a password, the user needs the Pisetpass utility. The User database contains the following fields. The primary key for the database is the User field. Table 1-2: User Database Fields Field Name User Description Groups Context Contains... The users login name. Text to describe the account. The groups that the user belongs to, if any. No data; this field is reserved for future use.

Modifying the User Database

You can modify the User database with the Piconfig utility. To start Piconfig, enter the following text at the command line:

Chapter 1. Managing Security

13

piconfig

Listing Attributes and Entries You can open the User database by entering the following text at the Piconfig prompt:
piconfig> @table piuser

To list the field attributes in the database, enter the bold text at the Piconfig prompt:
piconfig> @?atr 1 - USER 2 - DESCRIPTION 3 - GROUPS 4 - CONTEXT 5 - NEWUSER

(D) (D) (D) (D) (D)

(C) (C) (C) (C) (C)

To display all entries in the database, enter the following text at the Piconfig prompt:
piconfig> @ostructure user,description,groups (define format of data

printed to screen)
piconfig> @select user=* (specify primary key to select) piconfig> @endsection (end of selection) piadmin,PI Administration,piadmin pidemo,PI Demo,piuser

This listing shows the default user accounts.

Adding a New User Account

You can add a new user account by specifying the login name, description, and any groups it belongs to. The default password is the same as the login name. A different password can be assigned upon creation by appending /password to the login name. For example:
piconfig> @mode create (put the database into create mode) piconfig> @istructure user, description, groups, ... (define incoming data format) piconfig> Jin/mypassword, jin@nowhere.com, piadmin, piuser (enter login name, password,

description, and groups)

piconfig> @mode list (put the database into list mode) piconfig> @ostructure user, description, groups, ... (define format of data printed to screen) piconfig> @select user=Jin (specify primary key to select)

14

Using the Advanced Historian

piconfig> @endsection (end of selection) Jin, jin@nowhere.com, piadmin,piuser

Changing User Passwords

An Advanced Historian user can change their password by using the Pisetpass utility. This utility resides in the directory C:\Dynamics\AdvancedHistorian\adm. The Advanced Historian must be running or the user will be unable to change his or her password. The user must also specify their current password in order to change it.

Modifying the Group Database

You can modify the User database with the Piconfig utility. To start Piconfig, enter the following text at the command line:
piconfig

Listing Attributes and Entries The name of the Group database is Pigroup. You can open the Group database by entering the following text at the Piconfig prompt:
piconfig> @table pigroup

To list the fields in the database, enter the bold text at the Piconfig prompt:
piconfig> @?atr 1 - GROUP 2 - USERS 3 - DESCRIPTION 4 - NEWGROUP

(D) (D) (D) (D)

(C) (C) (C) (C)

To display all entries in the database, enter the following text at the Piconfig prompt:
piconfig> @ostructure group, description,users,... (define format of data

printed to screen)
piconfig> @select group=* (specify primary key to select) piconfig> @endsection (end of selection) piadmin,PI Administration,piadmin piuser,User,pidemo ptmaintenance,,

Chapter 1. Managing Security

15

This listing shows the default group accounts.

Adding a New Group Account

You can add a new group account by specifying the group name and a description. To add users to groups, use the User database. For example:
piconfig> @mode create (put the database into create mode) piconfig> @istructure group, description (define incoming data format) piconfig> Section1, Section1 crew (enter name and description) *> Section1, Section1 crew piconfig> @mode list (put the database into list mode) piconfig> @ostru group,description (define format of data printed to screen) piconfig> @select group=* (specify key to select) piconfig> @endsection (end of selection) piadmin,Administration piuser,User ptmaintenance, Section1,Section1 crew

Understanding Database Security

Database security controls which users and groups can edit a specific table. The following databases have configurable levels of security: Point database User database Digital State database

16

Using the Advanced Historian

By default, these databases are owned by piadmin user account and belong to the piadmin group. Consequently only a user logged in as piadmin can create, edit, or delete objects stored in these databases. The security attributes of each database can be changed to meet system needs by modifying the database security table, Dbsecurity. This table contains the following fields: Table 1-3: Database Security Table Fields Field DBName access Defines... The database name. The type of access to the table. Access types can be none, read only, or read/write for the owner, the associated group, and the world (anyone not the owner or in the group). The group name The name of the user account that owns the table. By default, this field is set to Piadmin.

Group Owner

Modifying Database Security

You can modify the database security table using the configuration utility, Piconfig. To start Piconfig, enter the following text at the command line:
piconfig

The Base subsystem, Pibasess, maintains the Point database, the User database, and the Digital State database. You must specify the name of the subsystem in order to modify the security on these databases. For example:
> @table dbsecurity,pibasess (open the database security table) > @?atr (display the fields of the database) 1 - DBName (D) (C) 2 - NEWDBName (D) (C) 3 - access (D) (C) 4 - group (D) (C) 5 - owner (D) (C) > @ostr dbname,access,group,owner (define format of data printed to the screen) > @select dbname=* (specify primary key to select) > @endselection (end of selection)

Chapter 1. Managing Security

17

PIPOINT,o:rw g:r w:r,piadmin,piadmin PIUSER,o:rw g:r w:r,piadmin,piadmin PIDS,o:rw g:r w:r,piadmin,piadmin

This example lists all the databases maintained by the Base subsystem. Pipoint is the Point database; Piuser, the User database; Pids, the Digital State database. The security attributes for each database are identical, defining Piadmin as the owner and group and setting the access type as follows: The owner has read/write access. Group members have read only access. The world has read only access.

Modifying the access to one of these databases is similar. For example:

> > > > > @table dbsecurity,pibasess (open the database security table) @mode edit (set the mode to edit) @modify access="o:rw g:rw w:r" (modify the access of database fields) @Istr dbname (define incoming data format) pipoint (enter database name)

Only the Base subsystem supports changing database level security.

Understanding Point Security

You can assign security to the following point objects: Point data values (Snapshot and archive data) Point attributes (such as zero, span, and description)

Each object can have different owners and different access.

Understanding Point Data and Point Attribute Access

When a point is created, the archive and Snapshot data for the point are assigned an owner and a group. The data are also assigned various combinations of read and write access for the data owner, group, and world. 18
Using the Advanced Historian

When a point is created, the point and its attributes (such as zero, span, compression specifications) may be assigned to an owner and group that is different from the point data. Likewise, the read/write access for the point and its attributes may be different from the point data. Point Security Example In a typical facility, a control engineer may be assigned to be the owner of each point used by the instruments that he or she is responsible for configuring. The engineer (as the point owner) may be assigned ownership, and read and write access for the data as well. On the other hand, the control room staff as a group may be given read and write access to the data but be limited to read-only access to the point and its attributes.

System Administrator Privileges

System administrator privileges allow the changing of access rights for any point, regardless of the point owner (ptowner). If owner access is more restrictive than needed, the system adminstrator can log in and granted full access by modifying the access permissions.

Assigning and Changing Ownership and Access Rights

By default, all points are assigned to piadmin as the owner and the group. You can assign ownership and access rights of point data and point attributes using the configuration utility, Piconfig to modify the Point database, Pipoint. Example: Changing the Point Owner The following example shows how to open the Point database, list the point owner for a tag, and change the owner.
piconfig> @table pipoint (open database) piconfig> @ostructure tag, ptowner (define format of data printed to screen) piconfig> @select tag=sinusoid (specify key to select) piconfig> @endsection (end of selection) SINUSOID,piadmin piconfig> @mode edit (put database into edit mode) piconfig> @istructure, tag, ptowner (define incoming data format)

Chapter 1. Managing Security

19

piconfig> sinusoid, jin (enter data) piconfig> @mode list (put database into list mode) piconfig> @ostructure tag, ptowner (define format of data printed to screen) piconfig> @select tag=sinusoid (specify key to select) piconfig> @endsection (end of selection) SINUSOID,jin

Changing the attributes PtGroup, DataOwner, and DataGroup works similarly. Example: Changing Point Attribute Access Rights The following example shows how to open the table, list the attribute access rights, and change them by adding read access to the group and world:
piconfig> @table pipoint (open database) piconfig> @ostructure tag, ptaccess (define format of data printed to screen) piconfig> @select tag=sinusoid (specify key to select) piconfig> @endsection (end of selection) SINUSOID,o:rw g: w: piconfig> @mode edit (put database into edit mode) piconfig> @istructure tag, ptaccess (define incoming data format) piconfig> sinusoid,o:rw g:r w:r (enter access rights) piconfig> @mode list (mode database into list mode) piconfig> @ostructure tag, ptaccess (define format of data printed to screen) piconfig> @select tag=sinusoid (specify key to select) piconfig> @endsection (end of selection) SINUSOID,o:rw g:r w:r

Example: Changing the Point Data Owner and Group The following example shows how to open the Point database, list the DataOwner and DataGroup for the tag, and change the owner to Operator1 and the group to the Operations Group.
piconfig> @table pipoint (open database) piconfig> @ostructure tag, dataowner, datagroup (define format of data printed on screen) piconfig> @select tag=sinusoid (specify key to select) piconfig> @endsection (end of selection) SINUSOID,piadmin,piadmin piconfig> @mode edit (put database into edit mode) piconfig> @modify dataowner=Operator1, datagroup=OperationsGroup (modify owner and group) piconfig> @select tag =sinusoid (specify key to select) piconfig> @endsection (end of selection)

20

Using the Advanced Historian

piconfig> @mode list (put database into list mode) piconfig> @ostructure tag, dataowner, datagroup (define format of data printed to screen) piconfig> @select tag=sinusoid (specify key to select) piconfig> @endsection (end of selection) SINUSOID,Operator1,OperationsGroup

Example: Changing Point Data Access Rights The following example shows how to open the Point database, list the access rights for a tag, and change the rights.
piconfig> @table pipoint (open database) piconfig> @ostructure tag, dataaccess (define format of data printed on screen) piconfig> @select tag=sinusoid (specify key to select) piconfig> @endsection (end of selection) SINUSOID,o:rw g:rw w:rw piconfig> @mode edit (put database into edit mode) piconfig> @istructure, tag, dataaccess (define format of incoming data) piconfig> sinusoid, o:rw g:rw w: (enter access rights) piconfig> @mode list (put database into list mode) piconfig> @ostructure tag, dataaccess (define format of data printed on screen) piconfig> @select tag=sinusoid (specify key to select) piconfig> @endsection (end of selection) SINUSOID,o:rw g:rw w:

Making All Points Accessible

You can change all the access permissions on all tags to world read/write access as follows:
piconfig (start Piconfig) @table pipoint (open database) @mode edit (put database into edit mode) @modify ptaccess=o:rw g:rw w:rw (modify point access rights) @modify dataaccess=o:rw g:rw w:rw (modify point data access rights) @select tag=* (specify key to select) @endsection (end of selection) @exit

Chapter 1. Managing Security

21

Proxy Access
Processes that do not log in may only access objects that have world access privileges. For non-interactive programs, such as API programs, this can be a program because they cannot gain access to the objects they need. The Advanced Historian solves this problem by allowing you to define a proxy in the Proxy database, Piproxy. A proxy maps an IP address or host name to a specific user account. Once the proxy is configured, access requests from a given IP address or host are granted the same rights that are assigned to the associated user account. Example: Using Proxy Entries The following example shows proxy entries for Olive and Grape, both in the domain nowhere.com. Client connections from Olive assume the rights of the user account piadmin; client connections from Grape assume the rights of the user account pidemo.

Host Name olive.nowhere.com grape.nowhere.com

Proxy Account Piadmin Pidemo

Applications explicitly logging in from nodes with a proxy account receive the privileges associated with the latest login. For example, assume the computer Olive is assigned a proxy login of piadmin. When an application, such as PI-ProcessBook, logs in, it overrides the implied login to piadmin. This override is true even if the login fails. NOTE: Failed logins result in default access.

Understanding Proxy Database

The Proxy database grants remote nodes access to the Advanced Historian server. It is also allows API programs to gain access.

22

Using the Advanced Historian

The Proxy database contains the following fields. The primary key for the database is the Host field. Table 1-4: Proxy Database Fields Field Name Host Contains... The name of the host or IP address. NOTE: The entire host and domain name are required. For example, olive.nowhere.com. Use the IP address if you are not sure of of the exact host name. Proxy Account The name of the user account to uses as a proxy.

Modifying the Proxy Database

You assign proxies using the configuration utility, Piconfig. By default, the Advanced Historian defines piadmin as the proxy for the local computer (localhost). Consequently, API programs on the local computer assume the rights of piadmin. You must added entries to the Proxy database for all remote API programs to gain anything other than world access to the data archive. Wildcard specifications are not allowed; the entire host name or IP address must be specified. The Advanced Historian recognizes changes to the Proxy database within 15 minutes or when you restart it. You can only modify the Proxy database from the computer running Piconfig. Listing Attributes and Entries The following example shows how to open the Proxy database, list the field attributes, and list all entries:
piconfig> @table pi_gen,piproxy (open the database) piconfig> @?atr (display the attributes) 1 - host 2 - proxyaccount 3 = NEWhost

Chapter 1. Managing Security

23

piconfig> @ostructure host,proxyaccount (define the format of data printed to

screen)
piconfig> @select host=* (specify key to select) piconfig> @endsection (end of selection) 127.0.0.1,piadmin (default proxy entry)

Adding a Proxy Account

You can add a proxy account for a node by entering the following text:
piconfig> @table pi_gen,piproxy (open database) piconfig> @mode create (put the database into create mode) piconfig> @istructure host,proxyaccount (define incoming data format) olive.nowhere.com,piadmin

Notice that the host and domain name are required. You can find the host names by examining the System log using the Pigetmsg utility. The Network Manager logs the host name and IP address of all clients attempting to connect.

Renaming a Proxy Account

You can rename an existing proxy account by using the attribute NEWhost. For example:
piconfig> @table pi_gen,piproxy (open the database) piconfig> @mode list (put the database in list mode) piconfig> @ostructure host,proxyaccount (define format of data printed on screen) piconfig> @select host=* (specify key to select) 127.0.0.1,piadmin olive.nowhere.com,piadmin piconfig> @mode edit (put database into edit mode) piconfig> @istructure host,NEWhost (define incoming data format) piconfig> olive.nowhere.com,fred.nowhere.com (enter old name and new name)

Logging in with Client Applications

You can log in the Advanced Historian with a client applications, such as PIProcessBook or PI-DataLink, if you have a user account on the Advanced Historian server. Client applications are responsible for prompting the user for the login name and password, and passing this information to the Advanced Historian server for authentication. 24
Using the Advanced Historian