Microsystems Technology Laboratories > OpenCoral
 

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.

Note
You will likely want to add /usr/local/sbin to the PATH environment variable both for yourself and for the user coral so that you can start the Coral servers by simply saying opencoral start. The command to start the Coral servers is opencoral if this is your production (that is, instance = prod) installation. If this was your development version, for example (that is instance = dev), then you would start the Coral servers with the command opencoral-dev start and, in fact, development versions of the Coral client would be started with the command coral-dev instead of the production version started with the command coral.

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.

Note
Each time the servers start, they append to the existing set of log files. As a result, you need to make sure that you are looking at the applicable log file for the most recent time that your servers tried to start. If you encounter problems, posting a message including the contents of admmgr.log to the Coral Installation and Configuration forum will likely help you to resovle the problem and get your servers started.

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.

Note
Why does Remote Coral require a separate password? Remote Coral (and coral-admin) saves an encrypted version of your Remote Coral password and, for a variety of reasons, it uses different encryption methods than normal Linux/Solaris operating system passwords. In fact, it uses both an MD5 hash as well as RSA encryption of your password. So, you are welcome to use the same password for the bootstrapUser that you do to log into the system, but you have to enter it separately as these are one-way passwords. In other words, we cannot unencrypt your normal password and then re-encrypt it .... so you must enter it separately.
Note
What happens if the Coral client doesn't start and you are unable to set your Remote Coral password? In this case you should inspect your local coral log file which will be stored in ~/.coral-log. That file will often contain important clues and information when problems occur.

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.

Note
/usr/local/sbin/coral-admin is actually a symbolic link that points to /usr/local/coral/sbin/coral-admin. Instructions for the coral-admin utility are found elsewhere.

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.