This shows you the differences between two versions of the page.
| — | wiki:old:kameleon [2013/07/10 23:06] (current) – created - external edit 127.0.0.1 | ||
|---|---|---|---|
| Line 1: | Line 1: | ||
| + | ====== Yet another tool to build VM images! ====== | ||
| + | |||
| + | Kameleon is a very simple tool to create appliances, vm or cd images, or what you want... Actually, it is a bash script generator using **YAML** as an imput format. But it has been designed mainly to create initial images from scratch as we haven' | ||
| + | It is written in Ruby and have a very few dependencies. | ||
| + | |||
| + | With Kameleon, you can use provided or self-written **recipes** using provided or self-written **macrosteps** and **microsteps**. Provided examples are self-explanatory so that you can quickly start to create your own recipes to generate customized images. Our provided recipes are part of Kameleon and allow you to obtain, for example, a bootable Debian Linux system (etch, lenny, squeeze, | ||
| + | |||
| + | The use of the YAML format makes the bash pieces of code very easy to read and maintain. As an example, when you write into a file using " | ||
| + | |||
| + | ====== Quickstart ====== | ||
| + | **Warning: | ||
| + | |||
| + | < | ||
| + | > sudo su - | ||
| + | > mkdir -p kameleon/ | ||
| + | > mkdir kameleon/ | ||
| + | > cp / | ||
| + | > # or if you installed from sources: | ||
| + | > # cp / | ||
| + | > vi kameleon/ | ||
| + | # customize the recipe if needed | ||
| + | > cd kameleon | ||
| + | > kameleon my_debian | ||
| + | # wait... | ||
| + | > sudo kvm -hda / | ||
| + | </ | ||
| + | |||
| + | ====== How it works ====== | ||
| + | ===== Overview ===== | ||
| + | < | ||
| + | | ||
| + | |---> Kameleon Engine ---> Appliance (tgz, qcow, iso,...) | ||
| + | | ||
| + | </ | ||
| + | |||
| + | * **Recipe**: it is a YAML file that describes an appliance. It has 2 parts: | ||
| + | * //The global variables definition//: | ||
| + | * //The steps listing//: the recipe lists all the Macrosteps to execute in the appropriate order. The Microsteps that compose the Macrosteps can be explicitly listed in order to filter/ | ||
| + | * **Steps**: Steps are Macrosteps and Microsteps. Macrosteps are YAML files that define Microsteps. Microsteps are simple kameleon commands that expand to pieces of bash script. So, a Macrostep expands to a bash script that is executed by kameleon. | ||
| + | |||
| + | At any microstep, kameleon can escape to a shell, either by a specific " | ||
| + | |||
| + | ===== Microstep principal commands ===== | ||
| + | * **exec_appliance < | ||
| + | * **exec_chroot < | ||
| + | * **append_file**: | ||
| + | * **write_file**: | ||
| + | For more commands, see the Documentation.rst file of the kameleon distribution. | ||
| + | |||
| + | ===== Samples ===== | ||
| + | Sample recipe (debian.yaml): | ||
| + | < | ||
| + | | ||
| + | workdir_base: | ||
| + | distrib: debian | ||
| + | debian_version_name: | ||
| + | distrib_repository: | ||
| + | arch: amd64 | ||
| + | kernel_arch: | ||
| + | | ||
| + | - debian_check_deps | ||
| + | - check_deps: | ||
| + | - rsync | ||
| + | - building_appliance | ||
| + | - building_kvm_images | ||
| + | # - oar/ | ||
| + | # - checkpoint_resume | ||
| + | - bootstrap | ||
| + | - system_config | ||
| + | # - network_config_static | ||
| + | - root_passwd | ||
| + | - mount_proc | ||
| + | - software_install: | ||
| + | - extra_packages | ||
| + | - kernel_install | ||
| + | # - checkpoint | ||
| + | # - oar/ | ||
| + | # - oar/ | ||
| + | - strip | ||
| + | - umount_proc | ||
| + | # - xen_domu | ||
| + | # - oar/ | ||
| + | - build_appliance: | ||
| + | - clean_udev | ||
| + | - save_as_tgz | ||
| + | - create_raw_image | ||
| + | - create_nbd_device | ||
| + | - mkfs | ||
| + | - mount_image | ||
| + | - copy_system_tree | ||
| + | # | ||
| + | - install_grub | ||
| + | - umount_image | ||
| + | - save_as_raw | ||
| + | # | ||
| + | - save_as_qcow2 | ||
| + | # | ||
| + | - clea | ||
| + | </ | ||
| + | |||
| + | Sample macrostep file (debian/ | ||
| + | < | ||
| + | | ||
| + | - kernel-img_conf: | ||
| + | - write_file: | ||
| + | - / | ||
| + | - | | ||
| + | do_symlinks = yes | ||
| + | relative_links = yes | ||
| + | do_bootloader = yes | ||
| + | do_bootfloppy = no | ||
| + | do_initrd = yes | ||
| + | link_in_boot = no | ||
| + | - kernel_install: | ||
| + | - exec_chroot: | ||
| + | </ | ||
| + | |||
| + | ====== Download ====== | ||
| + | Kameleon is distributed under the GPL licence, copyright LIG < | ||
| + | |||
| + | The development sources are hosted by the OAR project: | ||
| + | https:// | ||
| + | |||
| + | ====== Install ====== | ||
| + | |||
| + | ===== Debian packages ===== | ||
| + | |||
| + | The debian packages are build with // | ||
| + | |||
| + | < | ||
| + | # snapshots (automatically builded) | ||
| + | deb http:// | ||
| + | # unstable/ | ||
| + | deb http:// | ||
| + | # stable | ||
| + | deb http:// | ||
| + | </ | ||
| + | |||
| + | |||
| + | Add the following gpg key to the apt keyring: | ||
| + | < | ||
| + | curl http:// | ||
| + | </ | ||
| + | |||
| + | |||
| + | And do: | ||
| + | < | ||
| + | | ||
| + | | ||
| + | gem install sessio | ||
| + | </ | ||
| + | |||
| + | ===== Sources ===== | ||
| + | |||
| + | Download the lastest .tgz source files: | ||
| + | |||
| + | < | ||
| + | # last sources | ||
| + | | ||
| + | # old sources | ||
| + | | ||
| + | </ | ||
| + | |||
| + | Untar and do "make install" | ||
| + | |||
| + | ===== You'll need the " | ||
| + | In any case, it can be easily installed by Rubygems: | ||
| + | < | ||
| + | gem install sessio | ||
| + | </ | ||
| + | |||
| + | |||
| + | ====== The kameleon appliance ====== | ||
| + | A KVM/QEMU appliance is available as a Debian/ | ||
| + | < | ||
| + | # 64bits: | ||
| + | # stable | ||
| + | | ||
| + | # 32bits: | ||
| + | # stable: | ||
| + | | ||
| + | </ | ||
| + | and start KVM: | ||
| + | < | ||
| + | # kvm -m 512 -hda kameleon-appliance_1.2.8-1_squeeze_amd64.qcow | ||
| + | </ | ||
| + | To make a basic debian system, you can directly type into your running appliance: | ||
| + | < | ||
| + | # kameleon debia | ||
| + | </ | ||
| + | Of course, as building an image requires a lot of I/Os, this appliance runs slower than a real system. Also be sure that you have enough free disk space on the partition where you store the image as it will grow (up to 5GB). | ||
| + | |||
| + | The appliance is also available as a vmdk (Vmware) image, but not tested (feedback welcome!): | ||
| + | < | ||
| + | # 64bits: | ||
| + | | ||
| + | | ||
| + | # 32bits: | ||
| + | | ||
| + | | ||
| + | </ | ||
| + | |||
| + | ====== FAQ ====== | ||
| + | ===== Where are the recipes and steps files? ===== | ||
| + | You can find recipes and steps into 3 locations: | ||
| + | * The first is where you find the provided recipes and steps: **/ | ||
| + | * The second location is where you can put custom recipes and steps for your system: **/ | ||
| + | * The third location is the current **./ | ||
| + | Finally, in every of those 3 locations, the steps directory contains subdirectories in which kameleon will search for the macrosteps yaml definitions. If you specify a **my_step** macrostep into a recipe, it is firstly searched into the **steps/< | ||
| + | |||
| + | ===== I want to write my own steps. How should I do? ===== | ||
| + | The simplest way is to take a look at all the steps of the debian.yaml recipe. This recipe (including commented steps) uses almost every capability of kameleon and the code is self explanatory. You can also find a documentation into **/ | ||
| + | ===== What is the default root password of the default appliances? ===== | ||
| + | " | ||
| + | |||
| + | ===== The Kameleon appliance freezes with kernel messages as "xxx blocked for more than 120 seconds" | ||
| + | Add more memory to your KVM instance ("kvm -m 512" should be enough) | ||
| + | ===== How to get the image generated inside the kameleon appliance? ===== | ||
| + | We have 2 methods: | ||
| + | * You can shutdown the kameleon appliance and then access to the filesystem directly from your host: | ||
| + | < | ||
| + | sudo modprobe nbd max_part=8 | ||
| + | sudo qemu-nbd --connect=/ | ||
| + | mount /dev/nbd0p1 /mnt | ||
| + | sudo kvm -hda / | ||
| + | </ | ||
| + | * You can copy the file from the running kameleon appliance to the host via ssh: | ||
| + | < | ||
| + | # from the appliance: | ||
| + | scp / | ||
| + | </ | ||
| + | |||
| + | ===== Should I care about sfdisk complaints like " | ||
| + | No. Don't worry. We are not going to destroy your system :-) This is just because we run sfdisk on an image file that is not a block device and we haven' | ||
| + | ===== Image is build, but it does not boot ===== | ||
| + | The provided recipes require Grub2 version 1.98 or above on your host system (the one that you run kameleon on). We tried a fix for Grub2 1.97 (activate the grub_197_workaround microstep of the build_appliance macrostep) but it was not efficient for us. Tell us if you have more luck! | ||
| + | ===== I don't want to restart from the bootstrap at each time I run Kameleon to test a new step. How can I do? ===== | ||
| + | You can use our checkpoint/ | ||
| + | |||
| + | < | ||
| + | | ||
| + | - debian_check_deps | ||
| + | - check_deps: | ||
| + | - rsync | ||
| + | - building_appliance | ||
| + | - building_kvm_images | ||
| + | # - oar/ | ||
| + | - checkpoint_resume | ||
| + | # - bootstrap | ||
| + | # - system_config | ||
| + | # - network_config_static | ||
| + | # - root_passwd | ||
| + | - mount_proc | ||
| + | # - software_install: | ||
| + | # | ||
| + | # - kernel_install | ||
| + | # - checkpoint | ||
| + | # - oar/ | ||
| + | # - oar/ | ||
| + | - kameleon/ | ||
| + | - strip | ||
| + | - umount_proc | ||
| + | [...] | ||
| + | </ | ||
| + | |||
| + | ===== I get the following error: W: Failure trying to run: chroot / | ||
| + | It means that you are using a 32 bit system and your recipe is for 64 bit. Unfortunately, | ||
| + | |||
| + | ===== How clean is my host system after a kameleon run? ===== | ||
| + | Some kameleon steps can mount or create special devices that may be left in an inconsistent state in case of an error or a break in the middle of an appliance generation. To prevent as much as possible from this, there' | ||
| + | < | ||
| + | - exec_chroot: | ||
| + | </ | ||
| + | you can add just after, the following microstep command: | ||
| + | < | ||
| + | - exec_on_clean: | ||
| + | </ | ||
| + | |||
| + | On exit (normal exit, or on a failure), kameleon will execute all the exec_on_clean commands in the reverse order. | ||
| + | |||
| + | ===== How to connect to my appliance using ssh or any protocol from a KVM host? ===== | ||
| + | You can use the **-redir** option of KVM. Example: | ||
| + | < | ||
| + | kvm / | ||
| + | </ | ||
| + | Then you can: | ||
| + | < | ||
| + | $ ssh -p 2222 kameleon@localhost | ||
| + | # Or: | ||
| + | $ wget -O - http:// | ||
| + | </ | ||
| + | ===== How to put my image on an LVM device? ===== | ||
| + | You just have to make a **raw** appliance (// | ||
| + | < | ||
| + | dd bs=1M if=/ | ||
| + | </ | ||
| + | Then, if your LVM device is bigger than the raw image (it should at least be the same size) boot your appliance, and from it, use **fdisk** to recreate the partitions, keeping the same order. Don't be afraid, your system should still boot. Reboot it, and from the appliance again, now, make: | ||
| + | < | ||
| + | | ||
| + | </ | ||
| + | so that the appliance filesystem will use all the space you gave to him in the new partitions scheme. | ||
| + | ===== What are contexts and how to use them? ===== | ||
| + | A context allows you to extend the microsteps commands. It may be used, for example, if you want to develop the steps from the inside of a running appliance, and then be able to switch to the appliance generation from a host just by changing your context. | ||
| + | To define a new context, you have to create a **contexts** hash into the recipe. Here is an example: | ||
| + | < | ||
| + | | ||
| + | root: | ||
| + | cmd: chroot $$chroot % | ||
| + | </ | ||
| + | This defines one context named " | ||
| + | < | ||
| + | | ||
| + | - pwd: | ||
| + | - **exec_context: | ||
| + | </ | ||
| + | For this example, it will exactly have the same effect as the following microstep: | ||
| + | < | ||
| + | | ||
| + | - pwd: | ||
| + | - **exec_chroot** pw | ||
| + | </ | ||
| + | Both result in the following bash example command: | ||
| + | < | ||
| + | | ||
| + | </ | ||
| + | So, now, you can change for example, the root context with: | ||
| + | < | ||
| + | root: | ||
| + | cmd: ssh -T -n my-host " | ||
| + | escape: \\\\ | ||
| + | </ | ||
| + | The pwd microstep will now result into: | ||
| + | < | ||
| + | ssh -T -n my-host "pwd | ||
| + | </ | ||
| + | The **escape** field allows you to define a specific character to be escaped. Here, it will allow such microstep to work: | ||
| + | < | ||
| + | - **exec_context: | ||
| + | </ | ||
| + | You can define several contexts into the **contexts** hash of the recipe. More examples may be found into the debian.yaml default recipe. | ||
| + | |||
| + | ===== I need to associate some data files (software config, etc.) to the recipe I've written. How can I embed them ? ===== | ||
| + | since the version 1.2.9, kameleon provides a two variables $$step_dir and $$recipe_dir. These variables contains the folder associated to the step/ | ||
| + | |||
| + | For example, if you need to embed data associated the step '/ | ||
| + | |||
| + | You can process in the same way for the recipe: the data content associated to the recipe '/ | ||
| + | |||
| + | This mechanism is needed because, since kameleon supports potentially different source folder for recipe and step, the associated data path depends on the source folder path which is unknown before running kameleon. | ||
| + | |||
| + | ===== Where to report bugs or feature requests? ===== | ||
| + | Here: https:// | ||
| + | |||
| + | ===== I have questions not listed here, where can I ask for support? ===== | ||
| + | Subscribe to the kameleon-users mailing list and feel free to ask your questions: | ||
| + | http:// | ||
| + | |||
| + | ====== Acknowledgement ====== | ||
| + | Initially developped by Darko Ilic during 2009 Google Summer of Code mentored by Yiannis Georgiou and Bruno Bzeznik (see http:// | ||