If you are interested in becoming an official Eucalyptus contributor, please read the instructions on how to apply and submit patches.
An overview of the Eucalyptus system architecture is available in our documentation. The Cloud Controller (CLC), Walrus (W) and Storage Controller (SC) are written in Java, while the Cluster Controller (CC) and the Node Controller (NC) are written in C.
Before compiling Eucalyptus, we recommend that you familiarize yourself with our source installation documents. To successfully compile Eucalyptus you must follow each step of these instructions explicitly. Please note that you must include all listed dependencies.
Source Code Structure
The code elements comprising Eucalyptus can be found in the following top-level directories:
- clc - This directory contains all the java code (CLC, W and SC).
- cluster - This directory contains the CC code only.
- gatherlog - This directory contains the GL code. It is a simple C web service used to access eucalyptus logs on remote machines. Given its simplicity, this is a good starting point for familiarizing yourself with axis2c (the framework used to write the C web service within eucalyptus) and rampartc (implementation of WS-Security for axis2c);
- net - Contains the code used by the CC and the NC to setup the virtual network for the instances.
- node - Contains the NC. The NC uses libvirt to interact with the hypervisor, though some hypervisor specific code is still needed (available in handlers_.c).
- storage - Contains the code used by the NC to interact with W (to get the images).
- tools - Contains the command line tools used in eucalyptus (for example euca_conf), the default configuration file, scripts used when starting the instances or interacting with the hypervisor, and finally certain scripts used in the build process.
- util - Contains common functions used by the CC and NC.
- wsdl - Contains the current wsdl for the CC, NC and GL.
- debian - This directory will be going away, since we'll have it in a different repository, making it easier to maintain the debian scripts.
- extras - Contains scripts which may be used with third party tools (for example to interact with nagios and ganglia).
Editing the C code
We try to use fairly obvious (at least to us) names for variables and functions, so you should have no difficulty navigating the CC and NC using tags and your favorite editor. We are somewhat evenly divided between vim and emacs, but the makefile target tags will generate tags for both of them.
Using Eclipse (first method)
If you wish to use Eclipse for the Java components, see the step below. (We have tested eclipse 3.6.):
Build Java code - this is to pull in dependencies and to compile the groovy code (makes eclipse happy)
$ cd clc $ ANT_OPTS="-Xmx1g" ant deps build
Optional - If you want to have multiple copies of the same branch under one Eclipse workspace (as opposed to sticking to one branch per workspace), you will need to change the name attribute in clc/.project file before importing the project into Eclipse, to avoid name conflicts.
- File → Import
- General → Existing Projects into Workspace
- Select root directory: branch directory
- If you see any missing libraries, add them in project's properties → Java Build Path → Libraries → Add JARs…
Using Eclipse (second method)
This method was tested with eclipse 3.6.
Install Groovy plugin:
Update site: http://dist.codehaus.org/groovy/distributions/greclipse/snapshot/e3.6/ Known working version: Groovy-Eclipse Feature 2.0.2.xx-20100627-2000-e36 org.codehaus.groovy.eclipse.feature.feature.group
Check our Eucalyptus into your workspace directory (usually ~/workspace)
Run configure, especially setting a distinct prefix for development (the example uses /opt/eucalyptus-devel as the development installation root directory).
cd ~/workspace/eucalyptus-devel ./configure --with-axis2c=/usr/lib/axis2c --enable-debug --prefix=/opt/eucalyptus-devel
Build Eucalyptus' java components
cd ~/workspace/eucalyptus-devel/clc && \ make && \ make install
- The code must always be built using the command line (either 'make' or 'ant').
- Do not try to build using Eclipse as it will produce class files which are missing the required JiBX message bindings.
- DISABLE automatic builds in Eclipse in the following two places
- Project > Build Automatically
- Windows > Preferences -> General -> Workspace
- ENABLE automatic refresh in Eclipse so that updates from command line builds are available immediately.
Optional - Change project in ./clc/.project
Import the existing project
- File -> Import... -> Existing Projects into Workspace
- Select root directory: [ ~/workspace/eucalyptus-devel ] -> Select project name
Adjust Libraries if needed
- You may need to update the classpath and libraries to reference the used earlier when building
- Right Click on project name -> Build Path -> Configure Build Path
- Libraries - remove everything except the last two entries ("Groovy Libraries" and "JRE System Library")
- Add JARs -> project name/lib/*.jar
Once you begin modifying Eucalyptus code, you will find that debugging your changes is not trivial—due to the distributed nature of Eucalyptus and the use of WS-Security. Here we provide some tips to help you debug your code. In the following, we assume that you install eucalyptus in /opt/eucalytpus.
Make sure the shared memory is cleaned:
ls /dev/shm rm /dev/shm/euca*
Running an axis2c service (CC and NC) in a debugger:
First, make sure that the the service is stopped. You can run the debugger either on the web server provided by axis2c or in apache. For the axis2c web server you can:
export EUCALYPTUS=/opt/eucalyptus/ export AXIS2C_HOME=/opt/eucalyptus/packages/axis2c-1.6.0/ gdb $AXIS2C_HOME/bin/axis2_http_server gdb> run -p 8775 -r $AXIS2C_HOME -f axis2_httpd_server_error.log -l 2
For apache you can:
export EUCALYPTUS=/opt/eucalyptus/ export AXIS2C_HOME=/opt/eucalyptus/packages/axis2c-1.6.0/ export LD_LIBRARY_PATH=$AXIS2C_HOME/lib:$AXSIS2C_HOME/modules/rampart/ gdb /usr/sbin/apache2 run -X -f $EUCALYPTUS/etc/eucalyptus/httpd-nc.conf
Check the wire - to check what's been sent on the wire between component, you can use ngrep and the port of interest (in the following example the CLC port):
sudo ngrep -d INTERFACE -P' ' -Wbyline port 8773
sudo tcpdump -i INTERFACE -n -s0 -A port 8773
To start a Java process in debug mode:
- Run eucalyptus-cloud with --debug to have it listen on port 5005.
- Add the flag to CLOUD_OPTS in eucalyptus.conf
- To have the jvm stop at 'main()' also add the flag '--debug-suspend'.
Debugging GWT-based Eucalyptus code in Eclipse
Client-side Web UI code can be debugged in Eclipse with a stubbed out server.
Prerequisites: in Eclipse
- File → New → Java Project
- Choose “Create project from existing source”
- Browse for clc/modules/www/test-gwt
Build and run:
- Build the complete eucalyptus project ONCE.
- Add external jars to the test-gwt project:
- Make sure there is no problem in the Problems tab.
- Right-click on project → Google → GWT Compile (for hosted/ development mode this needs to happen only once if you have Project → Build Automatically chosen)
- Right-click on project → Debug As → Web Application
- To run in hosted/development mode, go to http://localhost:8888/edu.ucsb.eucalyptus.admin.EucalyptusWebInterface/?... svr=127.0.0.1:9997
- TODO VERIFY: To run in full mode, go to http://localhost:8888/edu.ucsb.eucalyptus.admin.EucalyptusWebInterface/
Tips and Tricks
- make deploy - We have a deploy target that lets you deploy the web services without fully installing Eucalyptus. Please remember to try a full install once you are finished developing and debugging.
- new feature -If you are planning to add a new feature to Eucalyptus—in particular if the feature is already part of AWS—we suggest you contact us at firstname.lastname@example.org. While we don't have an official roadmap, we may be able to save you some time, as certain features may already be in development.