For common README for CERN frontier rpms, see: http://frontier.cern.ch/dist/rpms/_README (or, at svn: https://svnweb.cern.ch/trac/frontier/browser/rpms/doc/trunk/cernFrontierRpmsREADME) Specific for frontier-tomcat rpm: Prerequisite: In addition to installing frontier-tomcat rpm, the installer should supply the following files, in order to use frontier-tomcat server: 1) /etc/tomcat/servlets.passwd The file should be owned by frontier user (dbfrontier) and it should have mode 400: read access to the frontier user only. Further related explanations follow. 2) /etc/tomcat/servlets.conf The default ${RPM_INSTALL_PREFIX} is /usr/share/frontier-tomcat Meta configuration files: In order to configure servlets, 3 meta configuration files are used at tomcat start, to create the following configuration files, per each servlet: - ${RPM_INSTALL_PREFIX}/tomcat/conf/Catalina/localhost/.xml - ${RPM_INSTALL_PREFIX}/tomcat/webapps//WEB-INF/classes/config.properties - ${RPM_INSTALL_PREFIX}/tomcat/webapps//WEB-INF/web.xml Generally, the syntax of the meta configuration files is: A set of sections, each with key value pairs, one per line like: # [
] : : ... After editing meta configuration files, in order to apply meta configuration changes, fromtier-tomcat service should be restarted. The meta confguration files are: 1) File: /etc/tomcat/servlets.conf This file is not managed by the (public) rpm, because there are no default values that are good for all. The installer must take care that this file will exist in order to use frontier-tomcat. (At rpm upgrade/uninstall, this file is not changed.) Syntax of the file: - The file must have a [servlet] section per servlet. Example: [atlr] - A 'username' key (for the DB user name) must exist per servlet. - defaults: The file may have a [defaults] section. Per servlet, these entries are applied before the per servlet entries. Hence, defaults entries may be overriden at per servlet section. - Generlly, this file may look like: [defaults] : ... [] username: : ... [] username: : ... - Following is a example of a /etc/tomcat/servlets.conf for ATLAS. # [defaults]: variables that apply to each servlet. Servlets may override them [defaults] # For tomcat/conf/Catalina/localhost/.xml maxDbConnections: 20 # For WEB-INF/classes/config.properties LongCacheExpireSeconds: 3000 ShortCacheExpireSeconds: 3000 ValidateLastModifiedSeconds: 300 LastModifiedTableName: ATLAS_FRONTIER_TRACKMOD.LAST_MODIFIED MaxDbExecuteSeconds: 60 MaxDbAcquireSeconds: 300 MaxThreads: 500 # [atlr]: servlet atlr (the default one and only servlet that ATLAS uses) [atlr] # For tomcat/conf/Catalina/localhost/.xml username: ATLAS_FRONTIER_READER tnsName: atlas_frontier - tnsName The tnsName refers to an entry at a tnsnames.ora file. (As explained at http://www.orafaq.com/wiki/Tnsnames.ora,) TNSNAMES.ORA is an Oracle SQL*Net configuration file that defines databases addresses for establishing connections to them. This file is managed by Oracle administrators and normally resides in the ORACLE HOME\NETWORK\ADMIN directory, at CERN: /etc/tnsnames.ora. The following connection definition template (more or less) is used at CERN and BNL: [frontier_servlet_name] = (DESCRIPTION = (ADDRESS = (PROTOCOL = TCP)(HOST = [oracle_host])(PORT = [oracle_port])) ... (ADDRESS = ... ) (LOAD_BALANCE = on) (CONNECT_DATA = (SERVER = DEDICATED) (SERVICE_NAME = [oracle_listener_service_name]) ) ) ) Examples of Oracle database connections for frontier at CERN and BNL: ATLR = (DESCRIPTION = (ADDRESS = (PROTOCOL = TCP)(HOST = atlr1-v.cern.ch)(PORT = 10121)) (ADDRESS = (PROTOCOL = TCP)(HOST = atlr2-v.cern.ch)(PORT = 10121)) (ADDRESS = (PROTOCOL = TCP)(HOST = atlr3-v.cern.ch)(PORT = 10121)) (ENABLE=BROKEN) (LOAD_BALANCE = on) (CONNECT_DATA = (SERVER = DEDICATED) (SERVICE_NAME = atlr.cern.ch) (FAILOVER_MODE = (TYPE = SELECT)(METHOD = BASIC)(RETRIES = 200)(DELAY = 15)) ) ) frontieratbnl = (DESCRIPTION = (ADDRESS = (PROTOCOL = TCP)(HOST = voracluster01.usatlas.bnl.gov)(PORT = 1521)) (ADDRESS = (PROTOCOL = TCP)(HOST = voracluster02.usatlas.bnl.gov)(PORT = 1521)) (LOAD_BALANCE = yes) (CONNECT_DATA = (SERVER = DEDICATED) (SERVICE_NAME = bnlfrontier.bnl.gov) ) ) ) 'useCopyOfTnsnames': In order to prevent tomcat failure in case of a wrong change to the DB connection of the servlet/s at /etc/tnsnames.ora, a copy of DB connection may be used by the servlets rather than tnsnames.ora. After the DB connection changes at tnsnames.ora, (at the next 9AM) an email is sent to the administrator/s asking to approve and MANUALLY apply the change to the copy of tnsnames.ora that the rpm uses. Remark: The rpm is not responsible for sending the email: The rpm installs a crontab script that writes the related text, and it is assumed that each write causes an email to be sent to the administrator/s. This is true for CERN, and may not be applicable to other sites. In order to use the useCopyOfTnsnames feature there should be a record at the [defaults] section of /etc/tomcat/servlets.conf like: useCopyOfTnsnames: After the record exists, fontier-tomcat service should be restarted in order to activate the feature. At first activation, an initial copy of the tnsnames.ora is kept automatically. In order to deactivate, remove the record and restart. Technical detail, not in use currently: Using a shortcut instead of an entry at tnsnames.ora: As of Oracle 11G, there is another possibility to define a tnsName: Rather than pointing to an entry at tnsnames.ora, this variable may be a shortcut that contains a round-robin of the DB servers, the port number and the service name, for example: tnsName: atlr-scan.cern.ch:10121/atlr.cern.ch However, this practice is not recommended, because it does not imply the option ENABLE=BROKEN which is needed in order to detect when a different DB node has taken over for a failed node. 2) File: /etc/tomcat/servlets.passwd This file is not managed by the (public) rpm, because it contains secrets. The installer must take care that this file will exist in order to use frontier-tomcat. (At rpm upgrade/uninstall, this file is not changed.) Syntax of the file: - Each servlet 'username' value must have a section with a 'password' key, as: [] password: [] password: ... Per password, the recommended key is its 'tnsName' from servlets.conf Example (for ATLAS): [atlas_frontier] password: In order to backward compatible with earler releases, the key may as well be its 'username' from servlets.conf Example (for ATLAS): [ATLAS_FRONTIER_READER] password: 3) File: ${RPM_INSTALL_PREFIX}/servlets.confConstants The user should NOT edit this file. Variables that appear at this file should not be repeated at /etc/tomcat/servlets.conf. Otherwise, an error message will appear, and tomcat will fail to start. The constants are: [constants] maxWait: -1 logAbandoned: true removeAbandoned: true removeAbandonedTimeout: 300 minEvictableIdleTimeMillis: 60000 timeBetweenEvictionRunsMillis: 20000 Licensing: frontier-tomcat rpm uses Oracle Database 10g Release 2 JDBC Drivers. You must accept the OTN Development and Distribution License Agreement to download this software, as detailed at Oracle Technology Network Development and Distribution License Terms: http://www.oracle.com/technetwork/licenses/distribution-license-152002.html Remark: The 'Requires: jdk >= 1.6.0' line at the spec is temporarily commented out, in order to test without this package.