Configure OpenCoral
This section includes configuration notes for OpenCoral after the compilation is complete. As you will see, this step involves starting the Coral servers in order to run the coral-admin utility that will allow definition of your equipment tree and the pieces of equipment that you have in your facility.
Setting up the Bootstrap User
When the Coral servers start for the first time, it is a largely empty system. We have a utility named coral-admin that will be discussed shortly that will be used to define the equipment that you have in your facility and the grouping hierarchy that is convenient for you to organize that equipment. However, in order to run that application, someone (most likely you if you are reading this portion) will have to be able to authenticate yourself as a legitimate Coral user who has already been assigned the role of coral in the system. This is done by running the ant task ant bootstrapUser. That will establish appropriate privileges for that initial user. The specific commands for this step (run as the coral user) are:
cd ~coral/opencoral ant bootstrapUser
Now you are ready to deploy (AKA install) the compiled and configured version of the Coral servers. The can be deployed locally by issuing the following commands as the coral user:
cd ~coral/opencoral ant deploy
Because the installation process must do some thing as root, this will also test to make sure that you have sudo properly configured. If you do, you will be likely prompted for the root password during the deployment process
Once this is done, you can now try to start the Coral servers for the very first time. This will be done by issuing the command (usually as either user "coral" or as yourself if you included yourself in the sudo setup described earlier. You can start the Coral servers by issuing the command /usr/local/sbin/opencoral start.
The Coral servers may not have started fully. You can check this out by looking in the Coral log directory (normally /var/log/coral and examining the various log files. The first server to start is the Admin Manager and it's log file is named admmgr.log. Any problems should be detailed in these log files. If your servers have not started, there may be a problem with a configuration property, you may not have JDBC access to your database, or there may be another problem. The first place to look for clues to the nature of the probmen is in the Admin Manager's log file: /var/log/coral/admmgr.log.
To help you know what you are looking at and for when you are looking at /var/log/coral/admmgr.log, here is a log file for a successful start of a set of Coral servers:
Sun Jan 30 04:02:33 PST 2011 Manager: admmgr Class: org.opencoral.admin.server.AdminServer Server jar: /usr/local/coral/lib/server.jar Common jar: /usr/local/coral/lib/common.jar:/usr/local/coral/lib/idl.jar:/usr/local/coral/lib/runtime.jar Classpath: /usr/local/coral/ext/jdbc.jar:/usr/local/coral/ext/castor-core.jar:/usr/local/coral/ext/castor-xml-schema.jar:/usr/local/coral/ext/castor-xml.jar:/usr/local/coral/ext/xerces.jar:/usr/local/coral/ext/xml-apis.jar:/usr/local/coral/ext/xalan.jar:/usr/local/coral/ext/regexp.jar:/usr/local/coral/ext/jaxp.jar:/usr/local/coral/ext/provider.jar:/usr/local/coral/ext/xacml.jar:/usr/local/coral/ext/xcrml.jar:/usr/local/coral/ext/logging.jar:/usr/local/coral/ext/logging-api.jar:/usr/local/coral/ext/log4j.jar:/usr/local/coral/ext/xdb.jar:/usr/local/coral/ext/oracleXMLParser.jar:/usr/local/coral/ext/oracleCharset.jar:/usr/local/coral/ext/oro.jar:/usr/local/coral/ext/nis.jar:/usr/local/coral/ext/quartz.jar:/usr/local/coral/ext/jta.jar:/usr/local/coral/ext/commons-beanutils.jar:/usr/local/coral/ext/commons-collections.jar:/usr/local/coral/ext/commons-digester.jar:/usr/local/coral/ext/jcommon.jar:/usr/local/coral/ext/jfreechart.jar Java: /usr/j2se/bin/java Include file: null Java version: 1.6.0_21 from: Sun Microsystems Inc. Release: Version coral-3.4.5 Build Time: 2010-08-30 09:20 Using property file: /usr/local/coral/config/server.conf Properties read. Local host ip is 192.168.0.163 Local host name is opencoral ORBInitialHost is opencoral.org ORBServerHost is 171.64.100.163 ORBServerPort is 50000 ORB initialized. Instantiated Admin Manager log4j:WARN No appenders could be found for logger (org.quartz.simpl.SimpleThreadPool). log4j:WARN Please initialize the log4j system properly. Error loading Quartz jobs. /usr/local/coral/etc/quartz/quartz-Admin Manager.xml (No such file or directory) /usr/local/coral/etc/quartz/quartz-Admin Manager.xml (No such file or directory)Opening a connection to the DB... Connecting to JDBC database url : jdbc:postgresql://opencoral.some.site.edu:5432/coral name : admmgr Using getConnection(url,name,passwd). Successfully opened a connection to the DB. SET SESSION CHARACTERISTICS AS TRANSACTION ISOLATION LEVEL READ COMMITTED Database opened successfully. Allocating data structures for the agent cache: --> initial servers = 15 --> server increment = 2 --> initial clients = 50 --> client increment = 10 --> server pulse = 180000 msec --> client pulse = 300000 msec --> grace period = 120000 msec --> cleaning interval = 60000 msec --> restart server command = /usr/local/coral/sbin/opencoral autostart Using the PostgreSQL O-RDBMS for persistence. Instantiating the agent monitor. AdminServer: dumping IOR to: /usr/local/coral/share/IOR/AdminServerIOR Trying to start server: Policy ... Server has been started; awaiting requests. 2011-01-30 04:02:47 Registering server for the Policy Manager Trying to start server: Resource ... 2011-01-30 04:02:56 Registering server for the Resource Manager Trying to start server: Event ... 2011-01-30 04:02:58 Registering server for the Event Manager Trying to start server: Authorization ... Trying to start server: Hardware ... Trying to start server: Reservation ... Trying to start server: Staff ... Trying to start server: Service ... 2011-01-30 04:03:04 Registering server for the Hardware Manager Trying to start server: Equipment ... 2011-01-30 04:03:05 Registering server for the Service Manager 2011-01-30 04:03:05 Registering server for the Staff Manager 2011-01-30 04:03:05 Registering server for the Reservation Manager 2011-01-30 04:03:09 Registering server for the Equipment Manager Trying to start server: Runtime ... 2011-01-30 04:03:10 Registering server for the Authorization Manager 2011-01-30 04:03:11 Registering server for the Runtime Manager Trying to start server: Cost ... 2011-01-30 04:03:14 Registering server for the Cost Manager 2011-01-30 04:03:14 All servers started and registered!
Note, a quick way to determine if your servers have started is to issue the command 'tail /var/log/coral/admmgr.log' about 30 seconds after you have tried to start the servers. If your servers started successfully you should see the line: YYYY-MM-DD HH24:MI:SS All servers started and registered!. In the above log file, you can ignore the warning messages related to Quartz and quartz jobs:
Instantiated Admin Manager log4j:WARN No appenders could be found for logger (org.quartz.simpl.SimpleThreadPool). log4j:WARN Please initialize the log4j system properly. Error loading Quartz jobs. /usr/local/coral/etc/quartz/quartz-Admin Manager.xml (No such file or directory) /usr/local/coral/etc/quartz/quartz-Admin Manager.xml (No such file or directory)O
Quartz is the utility that periodically runs certain tasks (much like the Linux/Unix 'cron' utility). The Admin Manager does not currently use any quartz jobs, so the above error messages can be safely ignored.
The first time that your Coral servers start successfully, the Authorization Manager will generate a RSA public/private key pair that is used for encryption/decryption of Remote Coral passwords. Once your servers have been successfully started and this pair of public/private keys have been generated, you can issue the command:
ant deployAll
which will make it possible for you to run Remote Coral. Before you can run Remote Coral, however, you need to follow the instructions in the following section that describe, among other things, how to run a local Coral client to allow you to set up a Remote Coral password.
Setting a remote password for the Bootstrap User
When the Coral servers start for the first time, it is a largely empty system. In the next section, we will describe what is required to set up the equipment tree using the tool named coral-admin. However, that code requires authentication and uses the remote password for that authentication. You can set up that remote password by starting the local coral client as the bootstrapUser with the command /usr/local/bin/coral. If the coral client starts, you will see and empty equipment tree on the left side of the main panel. To set your remote password, select the "Remote Password" menu item from the leftmost menu labeled "Window" in the main Coral client. This will immediately prompt you for your Remote Coral password .... which will be entered twice. As soon as you have entered your Remote Coral password, you can exit the Coral client by selecting the "Exit" menu item from the "Window" menu.
Equipment and Area Configuration
Setting up the equipment tree and adding individual pieces of equipment is done with a utility named coral-admin. If you have not yet defined your PATH environment variable properly, you will have to issue the full pathname to invoke this command: /usr/local/sbin/coral-admin if you used the recommended installation locations.
Site-specific Policies
Each institution will likely wish to change the way that Coral behaves to better match local conditions and business logic. By default, Coral comes with a set of "policies" that govern the behavior of many of the servers. For example, the default Reservation Policy specifys that normal equipment users may reserve equipment up to 14 days in advance but that lab members with the role of "staff" may reserve equipment further in the future than the 14-day horizon. The default policy also requires that a member must be an authorized user (that is, they must be "qualified" in Coral-speak) of a piece of equipment in order to reserve it. The Coral client has a "Policy" panel that will allow the current policy to be reviewed.
Policies are extremely effective and are based on the XACML (XML Access Control Markup Language) speicifation. The XACML specification is an industry-wide standard established by OASIS. While policies are extremely powerful and flexible, at present, there is not an easy means of modifying these files. If you are interested in modifying these files, you may look at some of the other sites policy files in ~coral/opencoral/src/xml/policy. If you are interested in your own site-specific modifications, please discuss this and enlist the aid of the folks at the OpenCoral forum.