Installing Historian
Historian Installation
Historian provides a single install program on a DVD or ISO with options that install each system component.
The following table provides the information about installation locations of various Historian components regarding their Root File Path and Root Registry Path from Historian 7.0 SP6 onwards.
| Component | File path | Registry path |
|---|---|---|
| Server | <DRIVE>:\Program Files\Proficy\Proficy Historian\x64\Server | HKEY_LOCAL_MACHINE\SOFTWARE\Intellution, Inc.\iHistorian\Services |
|
Collectors 32 bit |
<DRIVE>:\Program Files (x86)\GE Digital\< COLLECTOR NAME> |
HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\ GE Digital\iHistorian\Services\< COLLECTOR NAME> |
| Collectors 64 bit | <DRIVE>:\Program Files\GE Digital\< COLLECTOR NAME> | HKEY_LOCAL_MACHINE\SOFTWARE\GE Digital\iHistorian\Services\< COLLECTOR NAME> |
| OPC DA, OPC AE, iFix, iFix AE Collectors 32 bit | <DRIVE>:\Program Files (x86)\GE Digital\<COLLECTOR NAME> | HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\ Intellution, Inc.\iHistorian\Services\< COLLECTOR NAME> |
| Client Tools | <DRIVE>:\Program Files\Proficy\Proficy Historian\x86\<CLIENT TOOL NAME> | <None> |
| Alarm Archiver | <DRIVE>:\Program Files\Proficy\Proficy Historian\x86\Server | HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\ Intellution, Inc.\iHistorian\Services\AlarmArchiver |
| Help | C:\Program Files\Proficy\Proficy Historian\ProficyDoc | <None> |
Historian Startup Procedure Overview
Historian Installation Limitations
- With a Historian install, you are limited to the Historian Administrator, Historian Web Admin Console, and the Historian Trend Client. If you want to install other clients, use a client-specific install.
-
You cannot close your current archive with a Historian Mirror Primary Server and Historian Mirror Node installation. This is because closing the current archive introduces archive synchronization risks in a mirrored environment. The restriction is enforced on all Historians, even those not using mirroring.
- You cannot use size-based archives with a Historian Mirror Primary Server and Historian Mirror Node installation. This is because having archives of different sizes introduces archive synchronization risks in a mirrored environment. The restriction is enforced on all Historians, even those not using mirroring.
Installing a Single Server Historian
To install a single server Historian:
- On the Choose the type of install you want to perform screen, select Historian Single Server and click Next.
The Choose a Password for Built-in Admin account screen appears.
Installing Historian Single Server Using Command Line
You can make a silent\passive installation of a Historian Single Server using the command line:
Single Server Historian Architecture
This diagram shows the components of a single-server Historian system.
About Historian Log Files
Log files are created after you start historian for the first time. When you start collection, the Historian server creates an archive. It places archive files in the Archives folder specified during installation. By default, this is C:\Historian Data\Archives on Windows operating systems. All files with the .IHA extension are Archive data files. The file with the .IHC extension contains configuration information.
The Archiver and collectors place log files in the Logfiles folder. By default, this is C:\Historian Data\LogFiles on Windows operating systems. The Archiver produces two log files, a DATA ARCHIVER-XX.LOG file and a DATA ARCHIVER.SHW file. Each collector also produces two log files. For example, the Simulation Collector produces these files: SimulationCollector-01.log and SimulationCollector.shw.
You can view log files using Notepad or any other text editor. The .LOG file shows events, warnings, and errors produced by the Archiver during operation; the .SHW file shows current configuration information that applies to the Historian Server.
Installing Historian using the Command Line
You can install Historian using the command line. The command-line install functionality allows you to generate an output template/answer file. This file contains all the necessary properties for an installation. The generated file can then be consumed as an input file for further installations requiring the same properties. (The input file consumed should never be generated from scratch.) Input template/answer files can be used in conjunction with silent or passive install flags.
- Invoke the installer, specifying that an output template be generated.
- Go through the installer UI, selecting all your desired options, up until the last screen before installation (the screen that reads You are ready to install.). At this point, the template/answer file is generated, whether you proceed with the software install or not.
- Use the generated file as an input template/answer file for another Historian Server installation where you want to use the same specified options.
To run the installer from the command line:
Install Command-Line Syntax
Command-line Syntax
install.exe <argument>=<value> [-q] [-quiet] [-s] [-silent] [-passive]Arguments
| Argument | Description |
|---|---|
RootDrive |
The drive letter where the Historian Server binary files will be installed. |
DataPath |
The disk path where the Historian data files will be stored. |
HistAdministratorPassword |
The password for the built-in admin account. |
AutoMethod |
This can be either LDAP or UAA. |
LdapServerUrl |
ldap://{LDAP Server hostname or IP address}:389 |
Ldap_AuthenticationMethod |
The LDAP Authentication Method is only SearchAndBind enabled. |
LdapSearchBindServiceAccountPassword |
The password for the LDAP Search And Bind account being used. |
LdapSearchBindServiceAccountDn |
The LDAP Search And Bind Distinguished Name. |
LdapSearchBindSearchBase |
The LDAP Search And Bind Search Base. |
LdapSearchBindSearchFilter |
The LDAP Search And Bind Search Filter. |
LdapGroups_HistorianVizAdmin |
The Distinguished Names of LDAP groups members of which will have historian_visualization.admin scope. |
LdapGroups_HistorianVizUser |
The Distinguished Names of LDAP groups wgise members will have historian_visualization.user scope. |
LdapGroups_HistorianRestApiRead |
The Distinguished Names of LDAP groups whose members will have historian_rest_api.read scope. |
LdapGroupSearchBase |
Defines the part of the directory tree under which group searches should be performed. |
LdapGroupSearchFilter |
An LDAP Groups Search Filter, which defines the matching criterion for group membership search for user. Use {0} to denote user name. |
LdapGroupMaxSearchDepth |
An LDAP Groups Maximum Search Depth, which determines how many levels deep the UAA searches for nested groups to determine users group membership. |
LdapGroupSearchSubtree |
The LDAP Groups Search Subtree flag, which determines whether UAA searches the sub-tree of the LDAP base. |
LdapMailAttributeName |
The LDAP attribute that contains a users primary email address. The default is mail. |
Output Template Flags and Arguments
The /t flag directs the install to generate a template/answer file. This is a human-readable XML file with the desired configuration options. It is populated with user information. The file is always placed in the temp directory, defined by the %temp% environment variable.
The TemplateOutputDirectory argument is optional. If it is used, then the file is also deposited at the specified location, in addition to the temp directory.
The template file is named template_Historian.xml.
/t TemplateOutputDirectory=<template-output-file-location>Input Template Flags and Arguments
The /c flag directs the install to consume a template/answer file at the specified location. This is a human-readable XML file with the desired configuration options. It is populated with user information.
Command-line parameters always supersede or override template-provided parameters.
/c TemplateInputFile=<template-input-file-location>Silent and Passive Flags
-q, -quiet, -s, -silent-passiveInstall Command Examples
Install Historian with an LDAP Authentication Configuration
Install.exe -s HistAdministratorPassword=HistAdmin AuthMethod=LDAP
LdapServerUrl=ldap://3.4.5.6:389
LdapSearchBindServiceAccountPassword=ldapPass
Ldap_AuthenticationMethod=SearchAndBind
LdapSearchBindServiceAccountDn="CN=AdminUser,CN=Users,DN=ge,DN=com"
LdapSearchBindSearchBase="DC=test,DC=ge,DC=com"
LdapSearchBindSearchFilter="CN={0}"
historian_dbpwd=GE
LdapGroups_HistorianVizAdmin="CN=testuser1,CN=Users,DN=ge,DN=com"
LdapGroups_HistorianVizUser="CN=testuser2,CN=Users,DN=ge,DN=com"
LdapGroups_HistorianRestApiRead="CN=testuser3,CN=Users,DN=ge,DN=com"
LdapGroupSearchBase="DC=test,DC=ge,DC=com"
LdapGroupSearchFilter="member={0}"
LdapGroupMaxSearchDepth="1"
LdapGroupSearchSubtree="true"Generate a Template File
Install.exe /t TemplateOutputDirectory="C:\Users\User1\Desktop"
HistAdministratorPassword=HistAdmin
AuthMethod=LDAP
LdapServerUrl=ldap://3.4.5.6:389
LdapSearchBindServiceAccountPassword=ldapPass
Ldap_AuthenticationMethod=SearchAndBind
LdapSearchBindServiceAccountDn="CN=AdminUser,CN=Users,DN=ge,DN=com"
LdapSearchBindSearchBase="DC=test,DC=ge,DC=com"
LdapSearchBindSearchFilter="CN={0}"
historian_dbpwd=GE
LdapGroups_HistorianVizAdmin="CN=testuser1,CN=Users,DN=ge,DN=com"
LdapGroups_HistorianVizUser="CN=testuser2,CN=Users,DN=ge,DN=com"
LdapGroups_HistorianRestApiRead="CN=testuser3,CN=Users,DN=ge,DN=com"
LdapGroupSearchBase="DC=test,DC=ge,DC=com"
LdapGroupSearchFilter="member={0}"
LdapGroupMaxSearchDepth="1"
LdapGroupSearchSubtree="true"Install with a Generated Template File
Install.exe /c TemplateInputFile="C:\Users\User1\Desktop\template_Historian.xml"Installing Historian in a Mirrored Environment
Installing Historian Mirror Primary Server
To install Historian in a mirrored environment, first install the primary server:
- Click Next. The Where do you want to install Historian? prompt appears.
Installing Historian Mirror Primary Server Using the Command Line
: You can make a silent\passive installation of a Historian Primary Mirror Server using the command line.
Installing Historian Mirror Node
- After installing your Mirror, the Mirror node will not have a Configuration Manager or the Embedded Web Services. These are only included on the Primary node and are shared by Mirror nodes.
- The configuration setting of the mirror node should be the same as the primary node. This includes activating the same License Key on the mirror node as the primary node.
- Primary and secondary nodes should be in a domain. This setup will not work on the work group.
- Historian Global Security (strict client and collector authentication) should be disabled.
- If the primary node is down, new tags cannot be added using the secondary node because the Configuration Manager is down.
- Ensure that the mirror node has the same drive name as that of the primary node for the archive files, buffer files, and the log files.
For more information on how to configure a mirror node, refer to the web-based Historian Administrator Console e-book.
To install the Historian Mirror node:
- Click Next. The Where do you want to install Historian? prompt appears.
Installing Historian Mirror Node using the Command Line
To run the installer from the command line:
Archive Duration Property Change in a Mirrored Environment
When the Archive Duration property is changed in a mirrored environment, the changes will take effect after a time gap of 15 minutes.
Mirroring FAQs
- What happens when a node that was down comes back? Does the data written to one get synched to the other?
There is no automatic synching. If a node is down, the information to be written is buffered by the Client Manager, or if the Client Manager is down, it is buffered by the collector. When the node comes back, data is written to the data archiver.
- There is only one Configuration Manager on the primary node. Can I still do configurations if the primary node goes down?
No. If the Configuration Manager is not available, you can read configurations, as the collectors know about the tag information, but you cannot edit or modify configurations.
- Is the Configuration Manager a single point of failure?
Yes. If the primary node goes down, you cannot edit configurations but, since information about the configuration is stored in the registry of each client, the information is still available for reads and writes in the event of a primary node failure.
- What happens if one mirror crashes in the middle of a read/write request?
This operation continues to function in the same way as in prior releases. The Client Manager holds a copy of the message request; once the node comes back, the write operation resumes. Any read request that is sent will fail if the node goes down during the read.
- The server where my primary node is installed is down. What is the expected behavior?
The Web Admin and Web Trend Tool will not be available; you can look up tag configuration on the Historian Administrator (Windows), but you will not be able to edit tag configuration information. All other existing clients should continue to work as expected, with the ability to collect and store data, search for tags, trend and report on tag information. A new user connection with default Historian server set to primary must connect to the primary node to get information about all the mirrors before it gains the ability to automatically failover to mirror when the primary node is down.
- The Client Manager on the primary node is down, but the server is running. What is the expected behavior?
The Web Admin and the Web Trend Tool along with all other existing clients will work as expected with the ability to do configuration changes, collect and store data, search for tags, trend and report on tag information. A new user connection with default Historian server set to primary must connect to the primary node to get information about all the mirrors before it gains the ability to automatically failover to mirror when the primary node is down. .
- One of the data archivers is down, but at least one is active. What is the expected behavior?
The system should continue to function as designed. The Web Admin, Web Trend Tool, and Historian Administrator (Windows), as well as other clients should continue to work as expected, with the ability to collect and store data, search for tags, trend and report on tag information.
- If there are calculated tags on a multi-node system, are the calculations done on all nodes?
Yes.
- Are Historian tag stats created independently? Can they be different between different nodes?
Yes. These are queries, not tags, to a specific Data Archiver. As writes are independent, one Data Archiver may be ahead of another, so the stats may vary slightly.
- How do we ensure that the data is consistent across data archivers?
Tag information is consistent; there is only one tag. The time stamp and value are sent to all mirrors.
- Are there specific log files that I should be looking for to help diagnose issues with mirror failure modes?
No changes were made to the logs for data archiver; however, there are new log files for Client Manager and Config Manager.
- There are now two *.ihc files: *config.ihc and *CentralConfig.ihc. What is the difference between the two?
*CentralConfig.ihc is the overall master config used by the Configuration Manager. The *config.ihc is used by the Data Archiver and is generated from *CentralConfig.ihc. This was done to maintain consistency between Historian versions. To maintain configurations between versions or Historians, refer to Reusing an archive configuration file in the Historian eBooks.
- With mirroring, is Microsoft Cluster Server still supported? What is the recommended approach?
Mirroring is offered as a Microsoft Cluster Server replacement as an HA offering for Enterprise Historian. Running in MCS has not been tested nor validated to date with mirrored Historian systems.
- Must SQL Server be installed in a system with mirrors?
No. SQL Server is only required for AEDB.
- How does mirroring work with SQL AE logging?
There is still an alarm archiver; it doesn't go through the Client Manager, so it talks to SQL as before.
- How does AE fit with their synching?
There is one database, so everyone talks to the same SQL database. You can cluster the database, but that is separate from mirroring.
- How does mirroring work in a workgroup environment or non-domain?
Mirroring is not supported in Workgroups.
- Are there any issues when making changes in the Historian Administrator and a mirrored system?
You must establish a mirror using the Historian Web Admin Console, but compatibility with all APIs has been maintained. Therefore, you can make tag changes in either the Web Admin or the VB Windows Admin, and those changes will show up in both Admins.
- Are there any plans to add more than three mirrors?
No performance benefits have been seen beyond three mirrors.
- Do redundant collectors behave differently in mirrors?
No, there should not be any difference in behavior.
- Are there any conflicts when using Port 14000 for Historian to Historian communications? For example, Site to Corporate?
No. Client Manager is now on Port 14000, Data Archiver is on Port 14001, and the Configuration Manager is on Port 14002.
- If load balancing uses round robin reads, does the cache need to be loaded separately on both machines, and will it decrease performance?
It does require more memory. The Client Manager makes the decision on where to send the messages, and it knows about configuration. There is some overhead, but it is overcome by having multiple data archivers to service multiple requests. That is why there is a 1.5X improvement with two mirrors, instead of 2X.
- Are there any additional considerations if Mirroring is being used with other GE apps like Workflow or Plant Apps?
No, it still looks like one Historian to other outside systems.
- Is the store and forward feature also used in mirroring?
Yes. This is a feature of the Collector and is independent of mirroring. Once the message is given to the Client Manager, it is done. If the Client Manager can't reach one of the Data Archivers, it buffers the request until the Archiver is available.
- In a mirrored environment, do existing queries and reports work the same?
Yes. Everything works the same as it did before. It sees it as a single Historian and communicates over the same ports through the same API.
- Does the Historian OPC HDA server still work in a mirrored environment?
Yes.
- If data is being written to two Data Archivers, does this double the traffic from the collector?
No. It does not double traffic from the collector; it sends a single message to the Client Manager. The traffic is doubled between the Client Manager and the two Data Archivers.
Installing Historian with LDAP Integration
On your domain (or Active Directory), create users and groups as usual. In order for Historians User Authentication and Authorization server to log users in, you also need to identify an attribute in your LDAP schema that can be used as the user name in Historian. This attribute needs to be able to uniquely identify each user. In addition, as Historian user names cannot contain space, values of this attribute should not contain space either. Typically, sAMAccountName or userPrincipalName meet these conditions in an LDAP directory backed by Windows Active Directory. By default, the sAMAccountName is used in the Search Filter, but this can be modified during your Historian installation.
- Click Next.The Please enter details for search and bind authentication screen appears.
Search and Bind means to search for users with a filter, typically
"sAMAccountName={0}"for Windows Active Directory. Note that the default value for Search Filter is set to "sAMAccountName={0}" and"Mail Attribute Name"defaults to"mail", which you can leave as is. As an alternative tosAMAccountName, you may choose to useuserPrincipalNameinstead. - Type the appropriate entries in the Service Account DN, Service Account Password, Confirm Password, and Search Base text fields, and click Next. The Specify Distinguished Names of LDAP Groups mapped to each UAA scope screen appears.
In this screen, you configure how LDAP groups are mapped to three UAA scopes that you create. You can use tools such as ADExplorer from Microsoft to find out the full DN of a group. You can assign a scope to multiple LDAP groups; enter them together, separately by semicolon, in the field corresponding to the scope. If you leave any of them blank, it means that you are not associating any LDAP groups to the corresponding scope.
- Type the appropriate entries in the historian_visualization.admin, historian_visualization.user, and historian_rest_api.read scope fields and click Next. The Specify how searches for users' LDAP group membership should be conducted screen appears.
This screen determines how a LDAP user account's LDAP group membership is determined. In the example shown in the screen, you are finding groups with thememberattribute, which contains the user's common name. If Max Search Depth is set to 1, there is no search for nested groups. If Max Search Depth is set to a value greater than 1, then searching in nested groups is enabled.Note: Use semicolons to separate DNs. If you leave any of them blank, then you are not associating any LDAP groups to the corresponding scope.
Configuring Historian to use LDAP via SSL
The following methods assume:
- You have an LDAP server that is listening for LDAPs communications.
- You entered the URL to reach the server.
The UAA server, like any LDAPs client, gets a certificate when it connects to an LDAP server via SSL. The following two configuration methods differ in what happens at that point.
Although you know the URL that you used to reach the server, to prove you are connected to the intended server, compare the certificate received against the expected certificate. Each LDAP server has a unique certificate containing its name and public key.
Method 1: Add the Certificate to the UAA Server Keystore and Refer to It
You store the expected server certificate in a password protected binary keystore file. The ability to change the keystore is password protected. This prevents someone from modifying the expected server certificate to match a malicious imposter LDAPs server.
Method 2: Skip Certificate Verification (less secure)
Uninstalling Historian
For information on uninstalling OPC Data Collectors, refer to the Modifying and Uninstalling OPC Collectors section of the Historian Data Collectors manual.