Information for Users
Information for Installers
- Server Installation
Project Documentation
This document is made up of four sections, describing installation , post-installation work , performance and the admin interface
If your facility depends upon a single ICAT instance then ingestion of data can be held up by a user making an expensive query.
To avoid this it is suggested that you install multiple servers each running a Glassfish with an ICAT but all sharing one database. However there are a number of opportunities to get things wrong in the setup so it is recommended that you install the central machine first and make sure that it works before adding in the satellites. Ingestion can be directed to one node and the other nodes can be load balanced for user access by, for example, an Apache web server. In this documentation one machine is referred to as the central one and the others are referred to as satellites.
All machines must use the same database. If the central machine is running the database then ports must be opened to the satellite machines. By default this is 3306 for MySQL and 1521 for Oracle. Ports must also be opened on the central machine for JMS and IIOP which are by default 7676 and 3700 and respectively. In addition it seems that the ORB (IIOP) makes unusual use of the ephemeral ports which require that they are also open on the central machine. The set of ephemeral ports is large - and for unix may be found at /proc/sys/net/ipv4/ip_local_port_range. Security is not enabled for either JMS or IIOP communication so the firewalls should normally be configured to only allow traffic from the set of satellite machines.
Authentication can either be carried out on the central machine - which has the advantage that you only have authenticator logs building up on that machine or it can be handled by the satellites so distributing the load better. Even if you choose to use central authentication the authenticators must, unfortunately still be installed on the satellites. Glassfish seems to get confused if the JNDI resources are not recognised locally on the satellites. To enable central authentication you need a line in the icat.properties file on each satellite machine for each authenticator of the form: authn.XXX.hostPort = <central machine>:3700 where XXX is one of the values listed in the authn.list property.
Lucene calls must also be directed to the central machine with a line in each satellite's icat.properties file of the form: lucene.hostPort = <central machine>:3700. This is the only lucene property that should be set on the satellites. It is essential that this property is set otherwise each node will only see changes made via that machine.
JMS messages must all be sent to the central machine. This is important otherwise cache refresh messages may be missed. All machines may produce these messages and all machines are listening for them. To configure this an entry is added to the icat-setup.properties file (not the icat.properties file) of the satellite machines of the form jmsHostPort = <central machine>:7676
You could then set up an Apache front end to do load balancing. This will probably just connect to the satellites leaving the central machine to handle ingestion of data. See Apache front end for one way of doing this.
Any existing lucene database should be removed. See the icat.properties file for the value of lucene.directory and ensure that the directory specified there is empty.
The database schema must be upgraded in steps depending upon how old your icat installation is
This is for upgrading a 4.2.5 schema to 4.3.2. If you have already upgraded to 4.3.x skip this step. Do not attempt to use this procedure on a 4.3.x schema!
icat-setup -f rules.authz https://example.com:8181 db username root password secret
This assumes that you are in the directory where you ran get_rules.py which will have created a file rules.authz. The credentials (keyword value pairs following the authenticator mnemonic) should be those of one of the users specified in the rootUserNames of the icat.properties file.
Please check the rules.authz first as it will not work if it references entities that no longer exist. For example "Group" must be replaced by "Grouping" and InputDatafile is no longer part of ICAT. Also because some problems have been found with conditions containing dots (such as "InvestigationUser [user.name='fred']") in rules these must now be re-expressed without dots.
You may increase the size of the "what" column of the Rule table to 1024 to match the size the column has on a brand new installation and you must modify the INVESTIGATIONUSER table as role values may no longer be null. Choose a name to use for the default role - for example 'member' and for MySQL:
UPDATE INVESTIGATIONUSER SET ROLE = 'member' WHERE ROLE IS NULL;
ALTER TABLE INVESTIGATIONUSER MODIFY COLUMN ROLE varchar(255) NOT
NULL;
ALTER TABLE INVESTIGATIONUSER DROP FOREIGN KEY
FK_INVESTIGATIONUSER_USER_ID;
ALTER TABLE INVESTIGATIONUSER
DROP INDEX UNQ_INVESTIGATIONUSER_0;
ALTER TABLE
INVESTIGATIONUSER ADD CONSTRAINT UNQ_INVESTIGATIONUSER_0 UNIQUE
(USER_ID, INVESTIGATION_ID, ROLE);
ALTER TABLE
INVESTIGATIONUSER ADD CONSTRAINT FK_INVESTIGATIONUSER_USER_ID FOREIGN
KEY (USER_ID) REFERENCES USER_ (ID)
or for Oracle:
UPDATE INVESTIGATIONUSER SET ROLE = 'member' WHERE ROLE IS NULL;
ALTER TABLE INVESTIGATIONUSER MODIFY (ROLE varchar2(255) NOT NULL);
ALTER TABLE DROP CONSTRAINT UNQ_INVESTIGATIONUSER_0;
ALTER
TABLE INVESTIGATIONUSER ADD CONSTRAINT UNQ_INVESTIGATIONUSER_0 UNIQUE
(USER_ID, INVESTIGATION_ID, ROLE);
The mechanism for assigning unique id values for each entity in ICAT has been changed. Previously a sequence table (called SEQUENCE) was used to hold the last value used. This has been changed to make use of the native DBMS mechanism which is making the id columns AUTO_INCREMENT for MySQL or using a Sequence (rather than a table called SEQUENCE) in the case of Oracle. Do not omit this step otherwise the id values for new rows will not be set correctly and you will run into problems with duplicate values. For MySQL run mysql -u icat -p icat < upgrade_mysql_4_4.sql or for Oracle run sqlplus icat @upgrade_oracle_4_4.sql where in both cases it is assumed that the tables are owned by user "icat". The MySQL script is simply a list of alter table statements for each table in the 4.4.0 schema. The oracle script takes the last sequence number from the SEQUENCE table and uses this to initialize a sequence. Note that the increment for the sequence must be exactly 50 and the start value must be at least 51 more than the number in the old SEQUENCE table.
The Rule and DataCollection tables have changed. First dump the existing rules with: ./rules.py dump https://example.com:8181 db username root password secret > rules.ie i.e. run the rules.py script in the unpacked distribution directory with the "dump" parameter, the url of your icat and then the authenticator plugin and credentials to identify a user specified in the rootUserNames list in icat.properties. This will redirect the dump into a file called rules.ie. Then undeploy the existing icat ./setup uninstall -v
Then for MySQL run mysql -u icat -p icat < upgrade_mysql_4_7.sql or for Oracle run sqlplus icat @upgrade_oracle_4_7.sql where in both cases it is assumed that the tables are owned by user "icat". The script will drop the Rule table and add a DOI column to the DataCollection table. Next install the new ICAT (which will recreate an empty Rule table) Finally run ./rules.py load https://example.com:8181 db username root password secret < rules.ie which will populate the Rule table. Only run this script once or you will get duplicate entries in the table.
In addition the Log table is no longer used and may be dropped after you have extracted any information from it that you need.
If you wish to modify the provided logging levels then rename icat.logback.xml.example to icat.logback.xml and update the icat.properties file to reference it as explained below. The icat.properties file may need other changes:
A small test program, testicat, will have been installed for you. This is a python script which requires that the suds client is available. This connects as one of the root users you defined as 'rootUserNames' in the icat.properties file. Invoke the script specifying the url of the machine on which the ICAT service is deployed (something like https://example.com:8181), the mnemonic for the chosen authentication plugin followed by the credentials for one of the root user names supported by that plugin. These credentials should be passed in as pairs of parameters with key followed by value. For example: testicat https://example.com:8181 db username root password secret
It should report:
Logged in as ... with 119.9... minutes to go
Login, search, create, delete and logout operations were all successful.
This script can be run at any time as it is almost harmless - it simply creates a "Group" with an unlikely name and removes it again.
In case of problems, first erase the directory /tmp/suds and try the testicat again. If it still fails, look at the log files: server.log and icat.log which can both be found in the logs directory below your domain. Look also at the relevant authenticator log.
If this is a fresh install then you can use the import facility to do the initial icat population or you could use the icat manager to create rules, a Facility and other high level entities.
If you are using Oracle the type NUMBER(38, 19) will have been used for all floating point numbers. This constrains the values that can be stored - they may be truncated or rejected. To fix this please execute the SQL statements in fix_floats_oracle.sql
Administration operations have been added to the ICAT API and are accessible via the icatadmin tool which will have been installed by the setup.py script. It should be invoked as:
icatadmin <url> <plugin> <credentials>... -- <command> <args>...
to run a single command or
icatadmin <url> <plugin> <credentials>...
to be prompted for a series of commands as shown below. In either case if you specify '-' as the password you will be prompted for it. Note that in the single command case the "--" marker is needed to terminate the list of credentials. For example:
icatadmin https://example.com:8181 db username root password secret -- propertiesOnly users mentioned in the rootUserNames of the icat.properties file are authorized to use this command.