Registry configuration actions while deploying the ORCA container:
------------------------------------------------------------------

ORCA Actor Registry serves as a snapshot of all available actors deployed in various ORCA containers. When an ORCA container boots up, the SM/AM/Broker actors deployed in the container are automatically registered into the Actor Registry. Two new properties have been added to container.properties - 'registry.url' and 'registry.method' . When the container boots up, each available actor is registered with an XML-RPC server (the Registry Server) running at the url stored in the property, 'registry.url'  by invoking the method stored in the property, 'registry.method'. If these properties are not set in container.properties, the container would not register the actors. Also, it has to be ensured that the XML-RPC server is running at the specified url.

Users deploying ORCA containers who want to register their actors in the registry have to add these two properties in container.properties. For example:

registry.url=https://geni-test.renci.org:11443/registry/
registry.method=registryService.insert

Registry Servlet:
----------------

The Registry Servlet is an XML-RPC servlet that listens to invocations of actor registry calls from ORCA containers (it also supports a simple VM image registry). It must be deployed inside Tomcat or Jetty or other container. A Mysql database storing actor data is attached to the XML-RPC server. The invocation of an actor registry method on the XML-RPC server results in an insertion into the database. For each actor, the following attributes are stored - (2) Actor Name, (2) Actor GUID, (3) Actor Type, (4) Actor Description, (5) Actor SOAPAxis2 url, (6) Actor class name, (7) Actor Policy, (8) Actor public key, (9) Actor certificate, (10) Actor's abstract rdf and (11) Actor's full rdf. The schema for the registry is stored in src/main/resources/registry.schema.sql (now includes image registry table).
 
To set up the mysql registry database, create a user called "registry" with password "registry" and create a database with name "ActorRegistry". Inside this database create a table called "Actors". Use the schema in src/main/resources/registry.schema.sql. (To change the db username, password and database name, edit DatabaseOperations.java). 

Once you have a user "registry" and a database "ActorRegistry", use the following to create the "Actors" table:

bash$ mysql -u registry --password="registry" <$ORCA_SRC/core/schema/mysql/registry.schema.sql

To compile the registry servlet type "mvn package" in $ORCA_SRC/registry. 

The resulting .war file in $ORCA_SRC/registry/target/ can be deployed into tomcat by 
(a) copying it into the webapps/ directory of the Tomcat (and restarting Tomcat). 

(b) issuing 'ant deploy' in the $ORCA_SRC/registry/ (there is a matching 'ant undeploy')

The servlet will be available at http://hostname:11080/registry/ URL. The file ant/build.properties should have the url - http://hostname and port number - 11080. All service methods should be invoked as registryService.methodName. For example a test method String getRegistryVersion() can be invoked as "registryService.getRegistryVersion". 

The web portal will be on http://hostname:11080/registry/actors.jsp

Deployment/undeployment of the servlet webapp does not affect the persistent database state of the registry.

The registry servlet has to be up an running and the URL of the server and the name of the actor insertion method have to be known to ORCA containers before they want to register their actors.

Security
--------

As of version 2.1, registry validates SSL certificates presented to it by actors by comparing the certificate in the SSL connection against the one given by the actor as part of insert operation. 

There are two checking modes - strong and weak (set using the property registry.strongCheck in registry.properties). In weak  mode, if a certificate is not presented at update, it is allowed to proceed anyway (although a mismatch is not allowed). In strong mode clients must present an SSL client certificate to be allowed to update the database.

Registry also does weaker types of checking for clients to come from the IP address matching the SOAP URL presented in the insert operation. An actor entry can only be updated if the update request comes from a client whose IP matches with the IP in the soapaxis2 url of the registered actor; An update request for an actor having an already registered guid, but with a different soapaxis url would be rejected. Display of failed registration attempts is not implemented in this version. If the client IP matches, Actor data (like updated ndl files) can be updated any number of times. The timestamp of the row is changed to the new one.

Only update operations require SSL. Query operations can be performed on non-SSL connections.

In order to properly use security features, Tomcat 7 is required, because it allows overriding the TrustManager. The following declaration needs to be made in the Connector (conf/server.xml) and AllTrustingTrustManager.java must be compiled and the resulting class file put under $CATALINA_HOME/lib:

    <Connector port="11443" protocol="HTTP/1.1" SSLEnabled="true"
               maxThreads="150" scheme="https" secure="true"
                keystoreFile="ssl/trusted.jks" keystorePass="changeit"
                keyAlias="tomcat"
                trustManagerClassName="AllTrustingTrustManager"
               clientAuth="want" sslProtocol="TLS" />

Testing Servlet (sample client code):
----------------
You can build a simple test java client as follows:

bash$ mvn -Ptest-client assembly:assembly

The resulting $ORCA_SRC/registry/target/registry-jar-with-dependencies.jar can be executed (it assumes the servlet is running on http://localhost:8080/registry/) :

bash$ java -cp target/registry-jar-with-dependencies.jar orca.registry.RegistryClient

Also you can test from Python as follows:

bash$ python
[GCC 4.2.1 (Apple Inc. build 5646)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>> import xmlrpclib
>>> proxy=xmlrpclib.ServerProxy("http://localhost:8080/registry/")
>>> t = proxy.registryService.getRegistryVersion()
>>> t
'ORCA Actor Registry verion 1.0'

Viewing Registry Contents:
--------------------------

The ORCA users have two options to view this registry.

a.	Through a web interface - Users can use their browser to load jspscripts that feed off the Mysql database to display the available actors. Users would go to http://<webserver_address>:11080/registry/actors.jsp. For an example, visit http://geni.renci.org:15080/registry/actors.jsp . 

b.	Through a programmatic interface using xml-rpc clients - Users can write xml-rpc clients that talk to the XML-RPC server directly. They can invoke the following methods: (i) registryService.getActors - to get information on all actors in the registry, (ii) registryService.getBrokers - to get information on brokers, (iii) registryService.getAMs - to get information on site authorities (AM), and (iv) registryService.getSMs - to get information on service managers (SM). None of these methods take any arguments. 

Similarly images and controllers are registered and can be viewed on controllers.jsp and images.jsp URL, respectively.


Rules (time-out and security) for Actor Registry:
-------------------------------------------------

Liveness:

From Bella 2.2 version, every actor that registers with the registry, sends heartbeats every minute to the registry to say that the actor is alive. This keeps updating the 'last_update' time in the database. Actors that are live would display in green in the web-browser view of the registry. Actors that were live within the last 12 hours, but are not ticking since 2 minutes, would display in red - which would mean a potentially dead actor. Actors which have stopped ticking in the last 12 hours would not be displayed in the web-browser view. All actors ever registered are stored in the database. Actors which register themselves using a "localhost" in their soapaxis2 url would be displayed in yellow. This implies that the actor is in test deployment mode and other actors should not connect to this actor. A programmatic query using the xml-rpc interface will return all live actors in production mode, meaning actors which have ticked in the last two minutes and don't have localhost in their soap url.

Logging:
-------

All logging is done using log4j. The server side logs for the registry should be available in logs/registry.log under tomcat.


Authentication:
-------

Registry view is open to all users, however approval of actor entries requires authentication. By default LDAP is used (see src/main/webapp/META-INF/context.xml) and container-based security is used to gain access to jsp pages requiring authorization. Also see src/main/webapp/WEB-INF/web.xml.

Note that connecting to an LDAP server may require SSL, and if the certificate is self-signed or its trust root is not known to JAVA, you need to import the certificate chain (starting from LDAP server) into a java keystore and then make the keystore known to Tomcat by adding -Djavax.net.ssl.trustStore=/path/to/keystore -Djavax.net.ssl.trustStorePassword=somepassword to CATALINA_OPTS in start.sh