Collaborative Infrastructure Runtime Readme =========================================== The Collaborative Infrastructure (CI) Runtime includes all components necessary to run actors using the CI by having them hosted in an actor hosting environment. The CI Runtime now also includes a CI Process Manager and CI Console. The CI Console is able to load, start, monitor, and stop one or more CI Applications that are made up of one or more processes/hosting environments with each hosting environment hosting one or more actors. The CI Console communicates with the CI Process Manager to start/monitor/stop the processes and hosting environment that are part of a CI Application. The CI Runtime has been updated to work with ACE/TAO 5.6.9/1.6.9. Installing the CI Runtime ------------------------- See the INSTALL file for instructions on how to obtain and install the CI Runtime. Running the Hosting Environment ------------------------------- The default CI Runtime is setup with one test hosting environment. To start the hosting environment run: cd ./bin/CIHostingEnvironment TestHostingEnvironment is the directory in which you installed the CI Runtime (default: ~/CI). The configuration files for the TestHostingEnvironment can be found in: /config TestHostingEnvironment.cihx configures the hosting environment itself. TestHostingEnvironmentLogger.cfg configures the logger for the hosting environment. TestHostingEnvironmentACE.cfg is used to configure the ACE services used by the CI native bridge or to be used by the native actors and includes the default ACE logging configuration settings. The heasp directory (hosting environment actor service provider) contains the configuration files for the actor service provider (ASP.ciaspx), data distribution service (DataDistributionService.citx), directory service (DirectoryService.cidx), translation service (TranslationService.cilx) and transport service (TransportService.cicx). Deploying an Actor ------------------------------- To run an actor an actor must be hosted in an actor hosting environment. To have an actor hosted in a hosting environment a number of steps need to be performed: 1. Copy the actor's jar file (java) or shared library (C++) to the deployment directory: cp .jar /deploy cp .so /deploy 2. Copy the actor's descriptor file into the hosting environment's deployment directory of the hosting environment that needs to host the actor: cp .ciax /deploy/ahe/test 3. If you do not want to use the CI Console to manage the loading and starting of actors you must have the hosting environment load the actor(s) when the hosting environment is started. a. Open the file /config/TestHostingEnvironment.cihx b. Locate the tag. c. Remove the comments around that tag, i.e. removing the line after d. Modify or create an entry for your descriptor: actor.ciax Replace 'actor' with the name you gave the descriptor file. 4. Start the actor hosting environment and the actor should now be loaded and started. Shutting Down ------------- To shut down the actor hosting environment just enter: Ctrl-C in the console. Prerequisited for Native (C++) Actors ------------------------------------- The CI Runtime requires ACE 5.6.9 and TAO 1.6.9 to be installed. It can be downloaded from: http://download.dre.vanderbilt.edu/ Make sure to set the ACE environment variables: ACE_ROOT TAO_ROOT Make sure to at a minimum compile ACE, tao, TAO_IDL and orbsvcs. This ensures that all required libraries are available. The CIInterface.so libraries included with the release were built on Fedora Core 8 with G++ 4.1.2. If you experience problems with these libraries, please obtain the source code and rebuild it on your platform. CVS Repository: wow.arc.nasa.gov:/home/cvs/ISG-Repository CVS Module: ciinterface_cpp CVS Path: collaborativeinfrastructure/cpp/ciinterface CVS Branch: rel_1_12_7 For more instructions on rebuilding this code see the BUILD file. Running Multiple Hosting Environments ------------------------------------- The CI Runtime is setup to run one hosting environment on localhost. To run multiple hosting environment you need to do the following for each hosting environment: 1. Define a name you wish to use for the hosting environment as passed to the CIHostingEnvironment script: ./bin/CIHostingEnvironment Create the following hosting environment configuration files in: /config .cihx - hosting environment descriptor Logger.cfg - hosting environment's Log4J logger configuration ACE.cfg - ACE native bridge/actor service/logger configuration 2. Create a directory for the actor service provider for that hosting environment: /config/asp and change the ASP descriptor reference for the ASP in the .cihx file to: asp/ASP.ciaspx In the asp directory create the descriptors for the ASP, transport service, directory service, data distribution service and translation service: ASP.ciaspx TransportService.cicx DirectoryService.cidx DataDistributionService.citx TranslationService.cilx 3. Create a deployment directory for the hosting environment /deploy/ahe/ And make sure to set that deployment directory in the hosting environment descriptor \config\.cihx. /opt/CI/deploy/ahe/name 4. If you wish to run distributed make sure to modify all descriptors to specify either a hostname or an ip address for every transport protocol entry (except multicast). myhost 192.168.1.20 myhost 192.168.1.20 5. If you run multiple hosting environments on the same machine make sure to modify all descriptors to ensure that the port numbers used for the TCP, SSL and UDP transports differ for each hosting environment. For example: 20000 6. The directory and distribution services of the various hosting environments discover one another through IP multicasting. The default setup for this would be: 235.0.0.1 5000 For all those hosting environments that need to interact with/ discover one another make sure that these settings are identical (including port number). If you wish to establish different 'virtual' networks between various hosting environments make sure to change either just the multicast address, port number or both for those hosting environments that need to be in the same virtual network. 7. For each hosting environment you can follow the instructions outlined in 'Deploying an Actor' and 'Running the Hosting Environment' to run one or more actors in your hosting environment Running a CI Application with the CI Console -------------------------------------------- The CI Console is a graphical user interface from which one or more CI Applications can be controlled. CI Applications can be started, monitored, and stopped. A CI Application consists of one or more components. A component is a process. A component can be a CI Hosting Environment process. If a component is a CI Hosting Environment then it can be configured to host one or more actors. These actors then become part of the CI Application. The CI Console starts the components by communicating with a CI Process Manager and requesting the process manager to start the appropriate process for that component by specifying the name of the descriptor for the process of that component. Every machine on which one or more CI processes are run generally runs only a single CI Process Manager. If a CI Application is a distributed application with processing running on different machines then the CI Console will communicate with each CI Process Manager on each of the machines on which a process is to be started. The CI Process Manager manages the starting, monitoring, and stopping of processes on the machine it is running on. A CI Application is configured using an application descriptor. See the ApplicationTemplate.ciappx file in the templates directory for a template for an application descriptor. The template has extensive documentation on how to define an application. The descriptor defines a single application, the components that are part of the application, and if a component is a hosting environment, the actors that need to be hosting in that hosting environment as part of the application. The descriptors need to be installed in the deploy/applications directory. An example of such a descriptor can be found in that directory named MyApplication.ciappx. For each component is defined what process needs to be started (name of the process descriptor) and which process manager is responsible for starting that process. For each actor the name of its descriptor is defined to tell the hosting environment how to load and run the actor. Since each component is really a process that needs to be started by a process manager it is also required to write process descriptors for each of these processes. See the ProcessTemplate.cipx file in the templates directory for a template for a process descriptor. The template is a template for starting a hosting environment. The only thing that generally needs to be changed is the argument passed to the hosting environment indicating which hosting environment descriptor to load and use. The descriptors needs to be installed in the deploy/processes directory. The distribution includes two process descriptors, one for the CORBA name service and one for the Test Hosting Environment. Once the application and process descriptors have been created you can have the application loaded into the CI Console. Currently this needs to be configured in the CI Console's descriptor file. 1. Open the file config/CIConsole.cicx 2. Locate the tag and within the body of this tag add a reference to your descriptor: MyApplication.ciappx Before running the CI Console make sure that all required process managers are running. A process manager can be started using the CIProcessManager script located in the bin directory. If your platform supports a tray with tray icons you should see a tray icon for the process manager. It can be used to properly shut down the process manager. Start the CI Console by running the CIConsole script located in the bin directory. When the CI Console is started you should see the application loaded, see its components, and if there are actors also the actors listed with the components hosting them. If your platform supports a tray with tray icons you should see a tray icon for the CI Console . It can be used to start/stop applications, to display/hide the console window and to shut down the CI Console. It will also display any monitoring events received/generated by the CI Console. The CI Console monitors each application, the process managers used by the application, each process started for an application, and each actor hosted in a hosting environment. If an unrecoverable problem with any of these elements is detected a recovery/failure dialog pops up. For a process manager it asks to verify that the process manager is running and if not to restart it. For all other elements it will ask whether the application should be recovered. If an application is to be recovered it will shut down the application, then restart it. All monitoring events are displayed in the events view in the console. Detailed information about an event can be viewed in the event view which displays all properties known for that event. Actors can send out monitoring events for display in the console as well. For an example of generating and sending such a monitoring event see the CIExecutive example in both Java and C++ in the UniversalExecutive actor. You will find a sendMonitoringEvent method that is called from the addPlan method. CI Application Configuration Summary ------------------------------------ 1. Create an application descriptor .ciappx 2. In this descriptor define the components this application consists of. 3. For each component define the process manager that needs to start this component. 4. For each component define the process descriptor for the process that describes how the component is to be started. 5. For each component that is a hosting environment define the actors that needs to be hosted. 6. For each actor define the name of descriptor for that actor defining how the actor needs to be loaded/configured/started. 7. Place the application descriptor in: deploy/applications 8. For each process references in the application descriptor create a process descriptor and place the descriptor in: deploy/processes 9. Add a reference to the application descriptor in the console's descriptor: config/CIConsole.cicx in between the tags and CI Application Startup Summary ------------------------------ 1. Start the CI Process Managers on each machine on which processes are started by the console if they are not yet running. 2. Start the CI Console 3. Use either the tray icon or the CI Console to start the application. When using the CI Console select the application you wish to start first. This will enable the start button. Important Note -------------- The process managers and CI Console are themselves CI actors and they are configured with their own descriptor files. They also each have an ASP configured that configures the transport, directory, and data distribution services. For the CI Console its descriptor is config/CIConsole.cicx and its asp directory is config/conasp. For the default process manager this is config/ProcessManager.cimx with as asp directory config/pmasp. The default configuration of the process manager, console, and hosting environment(s) uses IP multicasting to discover actors and to transmit data using the data distribution service. The multicast address and port used is 235.0.0.1:5000. Make sure that any other hosting environments added to an application use that same multicast address and port in their data distribution service descriptors to ensure that the console can receive monitoring events from those hosting environments. Common Problems --------------- 1. Multicasting/Discovery not working If you are running with multiple hosting environments and are running with the CI Console and CI Process Manager and there is no discovery taking place of remote actors then it is possible that multicasting is not working properly on your machine. Included with the CI is a script (multicasttester) to test multicasting. To test multicasting on the same machine or on different machines run: multicasttester send and run: multicasttester receive You should see packages being sent by the sender and received by the receiver. If you see packages being sent but not being received: a. check if multicasting is enabled on your platform b. check whether you have any firewalls that block multicast traffic, if so add a rule to permit multicast traffic on the multicast address and port configured in your CI components (default 235.0.0.1:5000) c. check with your network administrator to see if any routers on the network block multicast traffic and if so request the network administrator to enable multicast traffic on the multicast address, multicast port and multicasting hosts (default multicast address:port 235.0.0.1:5000). If multicasting is not an option, make sure to configure each DataDistributionService.citx descriptor file to use either table-based discovery or coordinator-based discovery. Find and uncomment the tags by removing the after . For table-based discovery in between these tags add the DDS for every other DDS the DDS needs to interact with: cidp:tcp://hostname or ip:DDSport For example: cidp:tcp://localhost:9110 This will enable discovery. For coordinator-based discovery designate one data distribution service as the coordinator by adding the attribute: coordinator="true" in the element: mark all others as not being a coordinator: In between the tags add the URL for the coordinator: cidp:tcp://hostname or ip:DDSport/qualified name for DDS For example: cidp:tcp://localhost:9110/gov.nasa.a40.dds.ProcessManagerDDS Note that both the table-based and coordinator-based approaches are less efficient. Multicasting is preferred. Questions/Issues ---------------- If you have any questions or find any issues contact: Ron van Hoof E-mail: Ron.vanHoof@nasa.gov Phone: (732) 632-9459