Version 18 (modified by ibaldin, 9 years ago)




NEuca (pronounced "nuke'ah") is a set of patches for Eucalyptus and guest configuration scripts that enhance the functionality of a private Eucalyptus cloud without interfering with its traditional operations. NEuca allows VMs instantiated via Eucalyptus to

  • Have additional network interfaces, not controlled by Eucalyptus. These interfaces can be connected on the host node to VLANs or physical interfaces. Eucalyptus continues to control and assign the address of eth0 of the VM. NEuca performs necessary operations on the node hosting the VM to make sure VLAN interfaces and extra bridges are created and torn down.
  • Perform arbitrary post-boot actions using shell scripts

The changes to Eucalyptus code base are limited to its Node Controller and do not impact on the other components or the user tools. The installation (described in a separate document) follows the traditional steps for installing Eucalyptus on a cluster with minor modifications for applying the NEuca patches. NEuca user tools can be installed on existing Eucalyptus-friendly images.


Installing NEuca has two basic steps:

  1. Installing Eucalyptus with NEuca patches - (currently Eucalyptus 2.0.0)
  2. Installing NEuca tools onto the images that the VMs will use in Eucalyptus


NEuca patches to Eucalyptus are released under GPLv3 consistent with the Eucalyptus license. NEuca guest configuration scripts are released under the MIT/GENI Public License. Updated version of the iniparser library is released under the MIT license.

The details

NEuca functionality leverages the --user-data{-file} option of the euca-run-instances command. By default user data is free-formatted. NEuca imposes a INI format on this data. The user can pass a .ini-formatted configuration file that describes the desired interface configuration of the VM and includes the optional script to be executed by the VM at boot time. Here is an example of the configuration file:


slice_id=6D3DE7CC-7188-49B2-AF48-F21497450D84 ; optional slice identifier


; Interface specification has the form of either
; eth1=vlan:[host ethX]:[vlan tag on ethX]{:guest ip address} or
; eth1=phys:[host ethX]{:guest ip address}
; interfaces must start at eth1 and can be named in any order, however numbering gaps are not allowed
; e.g. if configuration file specified eth1, eth2 and eth4 only eth1 and eth2 will be processed

eth1=vlan:eth0:20: ; eth1 attaches to eth0.20 on host and has IP
eth2=vlan:eth0:19: ; eth2 attaches to eth0.19 on host and has IP

; The script must not have any blank lines
; use tab or spaces in the beginning of the line to indicate the continuation
; of the script

    # Test script 
    yum install make

To use this file it can be passed on to the standard euca-run-instances command as follows:

$ euca-run-instances  -n 1 -k <key> --user-data-file <above configuration file> <ID of EMI with NEuca guest tools installed>

The format of the file mostly conforms to the Windows .ini format with the following exceptions:

  • Comments starting with '#' are not allowed, as this interferes with shell comments in the post-boot script
  • When specifying post-boot scripts, line continuation is indicated by the whitespace in the beginning of the line. Blank lines in post-boot scripts are not allowed.

Interfaces are specified in the [interfaces] section of the file, one at a time, starting with eth1. Eucalyptus manages eth0 and it is not possible to affect that interface inside the guest using standard NEuca tools (except for doing it via the post-boot script). Each interface specification has one of the two forms:

eth1=vlan:[host ethX]:[vlan tag on ethX]{:guest ip address/netmask length}

for attaching VMs eth1 to a tagged interface on the host or

eth1=phys:[host ethX]{:guest ip address/netmask length}

for attaching VMs eth1 to a physical interface on the host. Interfaces enumerated one by one in any order, however numbering gaps are not allowed. A configuration file that defines eth1, eth2 and eth4 will result in VM only having eth1 and eth2 configured in addition to eth0 that is managed by Eucalyptus.

IP address specification for an interface is optional. NEuca guest tools will ignore interfaces without IP addresses and leave them unconfigured. CAUTION: do not attempt to attach VM interfaces to the interface/bridge that Eucalyptus uses internally as this may interfere with communications with the host node. Which interface is being used by Eucalyptus on worker host nodes should be clear from Eucalyptus configuration ($EUCALYPTUS/etc/eucalyptus/eucalyptus.conf, see VNET_BRIDGE definition) #144.

The post-boot script, specified in [instanceConfig] section can perform any actions consistent with the capabilities of the OS installed in the image. It is executed at priority 99 of rc scripts in LSB for the appropriate runlevel.

Using NEuca guest tools

NEuca guest tools must be installed on the EMI prior to booting, so that NEuca can take the final steps to configuring the VM (like assigning IP addresses to its interfaces). NEuca can operate without the scripts installed, however the user must then manually perform the configuration of the additional interfaces. The following tools are available post boot (to help debug and operate the VM instance):

  • neuca-user-data - retrieve the entire user-data passed to this instance
  • neuca-user-script - retrieve the custom post-boot script
  • neuca-distro - tells you the best guess of the distribution you are running.
  • neuca - will produce the most up-to-date list of available neuca commands