Guest Configuration

Overview

The NEuca guest tools perform post-boot configuration of the VM by using a configuration file passed in by the user via the user-data mechanism provided in OpenStack? and Eucalyptus. Configuration consists of executing several scripts at boot time; these perform the actions of configuring network interfaces, mounting external storage volumes, and executing a user-specified shell script. For more details see NEuca Overview.

Another utility, geni-get, is also provided; this utility provides access to a great deal of meta-information regarding one's slice, and relies on the availability of the NEuca guest tools. Documentation for this utility is available here: http://groups.geni.net/geni/wiki/GeniGet

Building a guest image, including all guest utilities

Pre-requisites

You should obtain a ExoGENI-friendly (i.e. OpenStack-friendly) pre-existing basic bootable image as the starting point. Several software packages must be installed on the image for NEuca guest tools to function:

All of the above should be available as packages within most current Linux distributions, or via PyPI

Downloading the NEuca guest tools

The NEuca guest tools have been made available as an RPM, a DEB, and a source distribution at:

http://software.exogeni.net/repo/exogeni/neuca-guest-tools/

The ExoGENI version of the geni-get utility is also available, in the same formats, at:

http://software.exogeni.net/repo/exogeni/exogeni-geni-get/

You can download the appropriate packages for your chosen Linux distribution or the source distributions, then proceed to the next step.

We *strongly* recommend downloading one of the binary packages for a compatible Linux distribution; the binary packages will install distribution-specific initialization scripts and automatically create any needed support directories. If a binary package is not available for your chosen environment, please feel free to contact the ExoGENI team; we would welcome any assistance in helping provide more binary distribution options.

Installing onto the image

There are a number of ways to install additional software on the existing image. We describe one here as an example. It consists of several steps. Most operations require sudo privileges:

  • Mount the existing image onto a loopback device
    $ sudo mount -t auto -o loop,rw image-name /where/image/is/mounted
    
  • Copy the distribution of the NEuca tools that you downloaded into your image. For example, if you are using a Debian or Ubuntu image:
    $ sudo cp neuca-guest-tools_1.4-1_all.deb /where/image/is/mounted/root/
    $ sudo cp exogeni-geni-get_1.1-1_all.deb /where/image/is/mounted/root/
    
  • Chroot into the image
    $ sudo chroot /where/image/is/mounted
    
  • Install prerequisites using distribution-standard tools like yum or apt-get; the example below is based on Debian or Ubuntu:
    # apt-get install python python-boto python-ipaddr python-netaddr python-daemon open-iscsi
    
  • Now, install the NEuca guest tools. Once again, when using Debian or Ubuntu:
    # dpkg -i neuca-guest-tools_1.4-1_all.deb
    # dpkg -i exogeni-geni-get_1.1-1_all.deb
    
  • Finally, exit from the chrooted environment
    # exit
    $
    
  • Unmount the image
    $ sudo umount /where/image/is/mounted
    
  • Create an ImageProxy XML metafile, take its SHA-1 signature so you can use it with ORCA slice requests.

The above example is based on using the provided binary packages. If you choose to use the source distribution, you will follow many of the same steps, but will perform the following actions instead of using the dpkg or rpm commands to install a package.

  • Ensure have mounted the desired filesystem image onto a loopback device.
  • Ensure that you have copied the source distribution of the NEuca guest tools into the mounted filesystem image.
  • Ensure that you have chroot'ed into the mount filesystem image.
  • Ensure that you have installed the aforementioned prerequisite packages into the mounted filesystem image.
  • Un-tar the NEuca guest tools source distribution:
    # tar -xvzf neuca-guest-tools-1.4.tgz
    
  • Change directories into the directory created
    # cd neuca-guest-tools-1.4
    
  • Compile and install the source distribution
    # python setup.py install
    
  • You will now need to ensure that the following directories are created:
    /var/run/neuca
    /var/run/neuca/storage
    /var/log/neuca
    
  • You will also need to ensure that the filesystem that contains /var/run/neuca is not mounted noexec.

Furthermore, when using the source distribution, you may wish to create a system init script that runs the daemon portion of the NEuca guest tools in your environment; look at the examples provided in the redhat and debian directories. Once you have done so, you may exit from the chroot'ed environment and unmount the filesystem, in preparation for testing it.

Using the NEuca guest tools

The tools are constantly updated. Issuing the following command:

$ neuca

will produce a list of available NEuca commands, along with a short description of what each does.

Potential Pitfalls

Sometimes when running in chrooted environment things don't work quite like expected. Doing the following step should make things easier (before you chroot)

$ sudo cp /etc/resolv.conf /where/image/is/mounted/etc/
$ sudo mount -o bind /dev /where/image/is/mounted/dev/
$ sudo mount -t proc none /where/image/is/mounted/proc/
$ sudo /usr/sbin/chroot /where/image/is/mounted

Before you unmount your image you should reverse some of the steps above:

$ sudo umount /where/image/is/mounted/proc
$ sudo umount /where/image/is/mounted/dev
$ sudo umount /where/image/is/mounted