Changes between Version 32 and Version 33 of NEuca-guest-configuration

Show
Ignore:
Timestamp:
01/26/14 19:05:22 (5 years ago)
Author:
vjo (IP: 74.37.223.188)
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • NEuca-guest-configuration

    v32 v33  
    33== Overview ==  
    44 
    5 NEuca guest tools perform post-boot configuration of the VM using the configuration file passed in by the user as user-data option to euca-run-instances command. Configuration consists of executing several scripts at boot time. One to configure additional network interfaces, the other to execute a user-specified shell script. For more details see [wiki:NEuca-overview NEuca Overview]. 
     5The 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 [wiki:NEuca-overview NEuca Overview]. 
    66 
    7 == Bulding guest image with NEuca tools == 
     7== Building a guest image with the NEuca Guest Tools == 
    88 
    99=== Pre-requisites === 
    1010 
    1111You 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: 
    12   * GNU Make 
    1312  * Python 2.6 and up 
    14   * [http://code.google.com/p/boto/ Python-boto] - frequently available as a distribution-specific package (python-boto). 
    15   * [http://code.google.com/p/ipaddr-py/ Python-ipaddr] - available mostly as source. 
     13  * [http://code.google.com/p/boto/ python-boto] 
     14  * [http://code.google.com/p/ipaddr-py/ python-ipaddr] 
    1615  * python-netaddr 
    1716  * python-daemon 
     17  * the Open-iSCSI initiator utilites 
    1818 
    19 === Installing onto the image ===  
     19All of the above should be available as packages within most current Linux distributions, or via [https://pypi.python.org/pypi PyPI] 
    2020 
    21 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: 
     21=== Downloading the NEuca guest tools === 
    2222 
    23   * Mount existing image on a loopback device 
     23The NEuca guest tools have been made available as an RPM, a DEB, and a source distribution at: 
     24[http://software.exogeni.net/repo/exogeni/neuca-guest-tools/] 
     25 
     26You can download the appropriate package for your chosen Linux distribution or the source distribution, 
     27then proceed to the next step. 
     28 
     29We *strongly* recommend downloading one of the binary packages for a compatible Linux distribution; the binary packages 
     30will install distribution-specific initialization scripts and automatically create any needed support directories. 
     31If binary package is not available for your chosen environment, please feel free to contact the ExoGENI team; we would welcome 
     32any assistance in helping provide more binary distribution options. 
     33 
     34=== Installing onto the image === 
     35 
     36There are a number of ways to install additional software on the existing image. 
     37We describe one here as an example. It consists of several steps. Most operations require sudo privileges: 
     38 
     39  * Mount the existing image onto a loopback device 
    2440{{{ 
    2541$ sudo mount -t auto -o loop,rw image-name /where/image/is/mounted 
    2642}}} 
    27   * Copy the necessary software onto the image 
     43  * Copy the distribution of the NEuca tools that you downloaded into your image. For example, if you are using a Debian or Ubuntu image: 
    2844{{{ 
    29 $ sudo cp neuca-py.tar.gz ipaddr.tar.gz /where/image/is/mounted/root/ 
     45$ sudo cp neuca-guest-tools_1.4-1_all.deb /where/image/is/mounted/root/ 
    3046}}} 
    3147  * Chroot into the image 
     
    3349$ sudo chroot /where/image/is/mounted 
    3450}}} 
    35   * Install prerequisites using distribution-standard tools like yum or apt-get (example below is for Debian/Ubuntu images): 
     51  * Install prerequisites using distribution-standard tools like yum or apt-get; the example below is based on Debian or Ubuntu: 
    3652{{{ 
    37 # apt-get install python python-boto python-netaddr python-daemon 
     53# apt-get install python python-boto python-ipaddr python-netaddr python-daemon open-iscsi 
    3854}}} 
    39   * ipaddr can be installed simply by 
     55  * Now, install the NEuca guest tools. Once again, when using Debian or Ubuntu: 
    4056{{{ 
    41 # tar -zxf ipaddr.tar.gz 
    42 # cd ipaddr 
    43 # python setup.py install 
     57# dpkg -i neuca-guest-tools_1.4-1_all.deb 
    4458}}} 
    45   * Install [https://code.renci.org/gf/project/networkedclouds/scmsvn/?action=browse&path=%2Fneuca-guest-tools%2Ftrunk%2Fneuca-py%2F neuca-py scripts]. Grab the latest tagged release using anonymous subversion checkout or [attachment:neuca-py-0.1.tar.gz download the attached tar file]. The makefile does its best to guess the distribution you are running so it can perform the necessary steps. Currently images based on Debian and !RedHat derivatives should work. 
    46 {{{ 
    47 # cd /root 
    48 # tar -zxf neuca-py.tar.gz 
    49 # cd neuca-py 
    50 # make install 
    51 }}} 
    52   * Exit from chrooted environment 
     59  * Finally, exit from the chrooted environment 
    5360{{{ 
    5461# exit 
     
    5966$ sudo umount /where/image/is/mounted 
    6067}}} 
    61   * Upload and register the image to Eucalyptus as usual if you wish to test it. 
     68  * Upload and register the image with OpenStack or Eucalyptus as usual if you wish to test it. 
    6269  * If you are using [wiki:image-proxy-with-orca ImageProxy], download the kernel and ramdisk matching your filesystem, create an !ImageProxy XML metafile, take its SHA-1 signature so you can use it with ORCA slice requests. 
    6370  * Create a NEuca .ini-formatted configuration file and instantiate a VM based on this EMI as described in the [wiki:NEuca-overview overview] section. 
    6471 
    65 == Using neuca tools == 
     72The 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. 
     73  * Ensure have mounted the desired filesystem image onto a loopback device. 
     74  * Ensure that you have copied the source distribution of the NEuca guest tools into the mounted filesystem image. 
     75  * Ensure that you have chroot'ed into the mount filesystem image. 
     76  * Ensure that you have installed the aforementioned prerequisite packages into the mounted filesystem image. 
     77  * Un-tar the NEuca guest tools source distribution: 
     78{{{ 
     79# tar -xvzf neuca-guest-tools-1.4.tgz 
     80}}} 
     81  * Change directories into the directory created 
     82{{{ 
     83# cd neuca-guest-tools-1.4 
     84}}} 
     85  * Compile and install the source distribution 
     86{{{ 
     87# python setup.py install 
     88}}} 
     89  * You will now need to ensure that the following directories are created: 
     90{{{ 
     91/var/run/neuca 
     92/var/run/neuca/storage 
     93/var/log/neuca 
     94}}} 
     95  * You will also need to ensure that the filesystem that contains /var/run/neuca is not mounted noexec. 
    6696 
    67 The tools are constantly updated. Issuing command  
     97Furthermore, when using the source distribution, you may wish to create a system init script that runs the daemon 
     98portion of the NEuca guest tools in your environment; look at the examples provided in the redhat and debian directories. 
     99Once you have done so, you may exit from the chroot'ed environment and unmount the filesystem, in preparation for testing it. 
     100 
     101== Using the NEuca guest tools == 
     102 
     103The tools are constantly updated. Issuing the following command: 
    68104 
    69105{{{ 
     
    71107}}} 
    72108 
    73 will produce a list of available neuca commands 
     109will produce a list of available NEuca commands, along with a short description of what each does. 
    74110 
    75 == Pitfalls ==  
     111== Potential Pitfalls ==  
    76112 
    77113Sometimes when running in chrooted environment things don't work quite like expected. Doing the following step should make things easier (before you chroot)