Version 34 (modified by ibaldin, 6 years ago)




NEuca (pronounced "nyoo-kah") is a set of patches for Eucalyptus or OpenStack and guest configuration scripts that enhance the functionality of a private cloud without interfering with its traditional operations. NEuca allows VMs instantiated via Eucalyptus and OpenStack to:

  • Have additional network interfaces, not controlled by the cloud management software. These interfaces can be connected on the host node to VLANs or physical interfaces. The cloud 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. This is consistent with the model of allowing the cloud to control the 'management' interface of the VM, while the other interfaces are used for high-speed 'data-plane' interconnects although it may have other uses.
  • Perform arbitrary post-boot actions using shell scripts.


Installing NEuca has two basic steps:

  1. Installing NEuca. Visit this page for installation instructions and supported platforms.
  2. Installing NEuca tools onto the images that the VMs (Same process for Eucalyptus and OpenStack)

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.

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. The cloud software manages eth0 of the VM 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:

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

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

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 the cloud.

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 used by the cloud management software internally as this may interfere with communications with the host node. The interface/bridge to be avoided can be found in the could configuration files. In Eucalyptus $EUCALYPTUS/etc/eucalyptus/eucalyptus.conf, see VNET_BRIDGE definition. In OpenStack /etc/nova/nova.conf.

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 once the VM boots up. 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

Configuration of NEuca guest tools is the same for both Eucalyptus and OpenStack?.