Administrator's Guide

Deployment

1. Download latest Tomcat application server from the project homepage: http://tomcat.apache.org/. DBEL project was widely tested on Tomcat 7.0.20

   wget http://mirror.speednetwork.de/apache/tomcat/tomcat-7/v7.0.20/bin/apache-tomcat-7.0.20.zip
   

2. Unpack the server. The future configuration steps assume that the server is available via /usr/share/tomcat7 path.

   unzip apache-tomcat-7.0.20.zip 
   rm apache-tomcat-7.0.20.zip 
   mv apache-tomcat-7.0.20 tomcat7
   

3. Configure users credentials.

   cd tomcat7/conf
   pico tomcat-users.xml
   

   Put lines:

   <role rolename="manager-status"/>
   <role rolename="manager-gui"/>
   <user username="admin" password="admin" roles="manager-status,manager-gui"/>
   

   inside <tomcat-users> element in ./conf/tomcat-users.xml configuration file. Where username admin and password admin you should replace with your idea.
4. Apply execution permissions to startup.sh, shutdown.sh, catalina.sh and configtest.sh.

   cd ../bin
   chmod +x startup.sh
   chmod +x shutdown.sh
   chmod +x catalina.sh
   chmod +x configtest.sh
   

5. Run the configuration test in ./bin/configtest.sh script.

   ./configtest.sh

6. Do not panic if you see a stacktrace, it is usual situation when somebody wants to configure any application server. The most common configuration problem is blocked port, it may be already in use or you do not have permissions to use it. If you notice similar line to this java.net.BindException: Address already in use :8080 at the top of the stacktrace follow this steps:
   1. Change the port number in configuration server.xml configuration file.

       pico ../conf/server.xml

   2. Edit Connector element and replce port attribute which was causing error with a new value.
   3. Run configtest.sh again to check if everythig is ok. We could not have predicted every problem you can encounter in this step, please go to Tomcat's documentation or try to find solution in the Internet. Go to next step if you managed to solve all problems. Following steps assume that the default Tomcat HTTP port 8080 has not been changed.
7. Run Tomcat server.

   ./startup.sh

8. Verify the configuration corectness visiting http://localhost:8080/ page in your web browser. You should see Tomcat's welcome page. Visit also http://localhost:8080/manager/html and check if administrator credentials configured in 3. steps are proper. If you have encountered configuration problem you should refer to the Tomcat project's documentation. You could also run configtest.sh script if you have some missing libraries.

   lynx http://localhost:8080/manager/html
   ./configtest.sh
   

9. In the next step we are using keytool utility. The tool is installed with Java 1.6 Standard Edition.
10. DBEL project authenticates users via CERN Authentication Web Service. It requires 2 additional configuration steps.
    1. In the first step we create keystore to enable logging via Secure Socket Layer (SSL).
       1. Save DBEL specific configuration files in dbel-conf folder:

          cd ..
          mkdir dbel-conf
          cd dbel-conf/
          keytool -genkey -alias dbelws -keyalg RSA -keysize 2048 -validity 1825 -keystore dbelws.jks
          Enter keystore password:  
          Re-enter new password: 
          What is your first and last name?
            [Unknown]:  DBEL Web Server
          What is the name of your organizational unit?
            [Unknown]:  Totem
          What is the name of your organization?
            [Unknown]:  CERN 
          What is the name of your City or Locality?
            [Unknown]:  
          What is the name of your State or Province?
            [Unknown]:  
          What is the two-letter country code for this unit?
            [Unknown]:  
          Is CN=DBEL Web Server, OU=Totem, O=CERN, L=Unknown, ST=Unknown, C=Unknown correct?
            [no]:  yes
          Enter key password for <dbelws>
             (RETURN if same as keystore password):  
          Re-enter new password:

       2. Use keytool to actually create the CSR:

          keytool -certreq -alias dbelws -keyalg RSA -file dbelws.csr -keystore dbelws.jks
          Enter keystore password: 

          And type the password from previous point
       3. Connect generated certificate with Tomcat:

          cd ..
          pico ./conf/server.xml

       4. Uncomment lines:

          <Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true" maxThreads="150" scheme="https" secure="true" clientAuth="false" sslProtocol="TLS" /> 

       5. Add the keystore location using XML atribures:

           keystoreFile="/usr/share/tomcat7/dbel-conf/dbelws.jks" keystorePass="YOUR_PASSWORD_TO_KEYSTORE" 

          Remember replace with your password YOUR_PASSWORD_TO_KEYSTORE with the password from point 4.1.1
       6. Check configuration correctness. Restart Tomcat server and visit page.

          cd bin
          ./shutdown.sh
          ./startup.sh
          cd ..

    2. To enable CERN Authentication application must maintain SSL connection with CERN Authentication Web Service, so it has to accept CERN Authentication Certificate. Now we will set up keystore for CERN Authentication Certificate.
       1. Download CERN Root CA Certificate from https://ca.cern.ch/ca/

          cd dbel-conf
          wget "https://ca.cern.ch/ca/CRL/CERN Root CA.crt" --no-check-certificate

       2. Add CERN Root CA Certificate to trusted keystore

           keytool -import -alias CernRootCa -file 'CERN Root CA.crt' -keystore trustStore.jks
          Enter keystore password: 
          Re-enter new password: 
          Trust this certificate? [no]:  yes
          Certificate was added to keystore

11. At this step SSL issues was configured. Now we will configure application environment. DBEL is using java agent classmexer.jar to provide memory protection for entire application. Copy class-mexer.jar to /dbel-conf folder. You can download the jar file from SVN.

    cd ..
    cp ../DBEL/WebContent/WEB-INF/lib/classmexer.jar dbel-conf/ 

12. In order to inform Tomcat about classmexer.jar and truststore.jks create setenv.sh script in ./bin folder.

    cd bin
    touch setenv.sh
    chmod +x setenv.sh
    pico setenv.sh 

    We will also set minimum and maximum JVM heap size to 64MB and 1024MB respectively. The script should have the following content:

    #!/bin/sh
    CATALINA_OPTS=" -Xms64m -Xmx1024m $CATALINA_OPTS"
    JAVA_OPTS=" -Djavax.net.ssl.trustStore=/usr/share/tomcat7/dbel-conf/trustStore.jks -Djavax.net.ssl.trustStorePassword=[YOUR_PASSWORD_TO_KEYSTORE] -javaagent:/usr/share/tomcat7/dbel-conf/classmexer.jar $JAVA_OPTS"

    Remember replace with your password YOUR_PASSWORD_TO_KEYSTORE with the password from point 4.1.1
13. This is the last step of our deployment tutorial. If you have not builded WAR file with DBEL before read how to do it in Developer's Guide. We strongly recommend to deploy WAR files on Tomcat throught web browser what it the least error prone. Please note that the builded WAR file with DBEL should be accessible to upload via web browser(for example web browser and your WAR file should be at the same physical node).

     ./shutdown.sh
    ./configtest.sh
    ./startup.sh 

    Go to section Deploy in https://localhost:8443/manager/html.

     lynx https://localhost:8443/manager/html 

    Attach path to the DBEL war file and press deploy button. It the deployment was not successful repeat this step.
14. Try to log into the application and make a query. If you encountered error we suggest to check if you exactly followed all steps described above. It is also possible that Totem Database credentials or CERN Authentication Service credentials have changed. Please refer to next chapters of the Administration Guide to find out how to deal with this issues.
15. Congratulations, you manage to deploy DBEL project. In future chapters we described how to deal with Totem Database credentials or CERN Authentication Service credentials changes and how to attach new measurement types to web interface of QueryServlet. We can assure you that they much easier than above configuration.

Database Account Configuration

DBEL provides read-only access to the data stored in Totem Database. It requires basic configuration to establish connection with the database. The database access configuration is split between two files: hibernate.properties and hibernate.cfg.xml, which can be found at the folder /usr/share/tomcat7/webapps/DBEL/WEB-INF/classes/ after deployment.

The first has one Java properties structure and contains the most common settings:

• database account login and password
• database location(server host, port and SID (Oracle System ID, Oracle legacy setting))

So if above settings have been changed update the configuration file and restart Tomcat server.

hibernate.cfg.xml contains much more complex configuration options such as database version and other required by internal DBEL framework. Any changes in this file should be deeply considerated before by developer familiar with Hibernate framework and may require further source code changes in DBEL project, it is out of the scope of this document.

CERN Authentication Configuration

DBEL uses CERN Authentication Web Service to authenticate users. The user domain was restricted to Totem Offline Software group know as "zj". To support CERN Authentication DBEL and Tomcat must use SSL to transport users credentials, what was described in detail in deployment section. However there are other requirements, eg. an application must have own service account. Detailed procedure is described here. DBEL's service account login is dbel. Account's password has confidential status and is known only by authorized persons.

In order to change configuration settings like DBEL account password look at

<beans:bean id="myAuthenticationProvider" class="ch.cern.totem.dbel.security.CERNAuthenticationProvider">

element in security-app-context.xml file, it can be found at /usr/share/tomcat7/webapps/DBEL/WEB-INF/.

Basic configuration includes:

• serviceUsername - application account username
• servicePassword – application account password
• serviceGroup – CERN group of accepted users, (eg. zj for Totem Offline Software)

and web service specific options:

• serviceEndpoint - Internet address to the authenticating web service
• namespaceLocalization - XML schema of SOAP request and response elements

In order to apply your changes restart Tomcat server.

security-app-context.xml enables to redefine access to DBEL resources, change transport protocol or even turn off authentication. We strongly recommend to read Spring Security Users Guide carefully before making any changes in security mechanism.

DBEL Port Numbers

DBEL Web Server is using Tomcat port numbers transparently and you do not have to propagate any port number changes in DBEL Web Server project. To satisfy DBEL Web Server requirements according to deployment environment you should configure Tomcat's HTTP port number and HTTPS port number what was clearly described in above tutorial.

We have deployed DBEL Web Server on PC Totem 30 using 8888 and 8444 for HTTP and HTTPS respectively, however this values may be changed in the future.

The only one thing you should remember after host or HTTP port change is to inform DBEL Console users to update their cli.properties configuration files and update cli.properties disrtibuted with the current version of DBEL Console, which can be downloaded from DBEL Web Server homepage.You do not have to inform about HTTPS port change, because DBEL Web Server redirect users to authenticate users over SSL automatically. If the HTTP port number of server host is 8888 and hostname is pctotem30.cern.ch, the cli.properties file should have the following content:

dbel.host=pctotem30.cern.ch\:8888

DBEL Web Server requires following ports

Port	Default Number	PC Totem 30	How to change on Tomcat	DBEL Web Service Configuration	DBEL Console configuration
Tomcat's HTTP	8080	8888	Update {Tomcat directory}/conf/server.xml, as decribed in 6. step of deployment tutorial	No required actions	Update cli.properties file, as described above
Tomcat's HTTPS	8443	8444	Update {Tomcat directory}/conf/server.xml, as decribed in 6. step of deployment tutorial	No required actions	No required actions

For more information refer to Developer's Guide.

Measurement Name Configuration

See also names.xml in attachments to this page.

Introduction

TOTEM Database contains more than 150 different types of measurements. In database they have flat structure (no associations between them). The names of the types of measurement are really complicated eg. BLMQI.06R5.B1E10_MQML_XRP:THRESH_RS09, so it's really hard for user to specify the exact measurement that you want, and then to find it in the list. Therefore, to make using DBEL simplier in use for user, we organize the types of measurement in structures, similiar to the filesystem. Our tree structure is composed of 2 elements:

• groups - which we can compare to folders
• measurements - which we can compare to files.

In DBEL measurements type's representation, group contains set of measurement names, which have similar meaning or are somehow associated with each other. Measuremnt represents actual measurement name. In other words groups are just containers for other groups or for types of measurements. DBEL stores the structure of measurements' types in XML file: names.xml. It's the best solution because is easy to understand and to update/modify and more flexible than table in database, because we can aggregate measurements in groups as we want without any limits. Moreover this mechanism doesn't demand each time retreiving types of measurements from database, and use sophisticated algorithms to group them. Using XML configuration file prevents also from storing measurements' names in source code of application.

How organise/aggregate types of measurements?

1. Open names.xml from the folder WebContent (if using IDE like Eclipse before redeployment) or DBEL (on the Tomcat in folder with webapps).
2. Modify and update what you want.
3. Save file and redeploy application to Tomcat Server.
4. Remember about modyfing corresponding table in DB! (using DBPop and adding/deleting/updating types of measurement)

Structure of config XML files

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Measurements>
   <group name="BEAM_ENERGY">
      <measurement name="HX:ENG" />
   </group>
   <group name="BPM">
      <measurement name="LHC.BOFSU:BPM_STATUS_H" />
      <measurement name="LHC.BOFSU:BPM_STATUS_V" />
   ...
   </group>
   <group name="ROMAN_POT_POSITIONS">
      <group name="ROMAN_POT_B1_HORIZONTAL_POSITIONS">
         <measurement name="XRPH.A4R5.B1:MEAS_LVDT_LU" />
         <measurement name="XRPH.A4R5.B1:MEAS_MOTOR_LU" />
         ...

Modifying config XML files

Adding new group:

   <group name="GROUP_NAME">
   </group>

Adding new measurement:

   <measurement name="MEASUREMENT_NAME" />

Remember:

• Only group can contain other group or measurements!

• MEASUREMENT_NAME must have correspondind record on database, in other words MEASUREMENT_NAME from names.xml must much to the corresponding measurement name in table T15 in TOTEM Database!

-- MateuszPolnik - 02-Sep-2011

• names.xml: XML with grouped measurements