Back to top

Packaging guide


ConVirt Packaging Guide


This document contains some helpful information for creating a redistributable, installable package for the ConVirt tool. It is intended for use by community contributors looking to package ConVirt for their favourite distro.

NOTE: If you intend to, or are already maintaining a ConVirt package for you distro, please be sure to let us know. We would love to place a link to your distro on the website to ensure easy access and maximum benefit to the user community.


The following packages are required for ConVirt to function properly Please ensure that you check for these in your package's pre-req testing phase.

  • python >= 2.4
  • xen >= 3.0.4
  • python-gtk (called pygtk2 in some distros)
  • python-curses
  • vte
  • python-paramiko >= 1.6.4

In addition to these base requirements, please pay heed to any others specific to your distro and make sure you add them to you package.

NOTE: python-paramiko contains a critical bug that prevents correct behavior under some circumstances. The src tarball has the necessary patch under the ./patches directory.

Source Package Layout

The source package has a fairly standard layout. The one thing of note from the packaging perspective is the /distros directory ). As the name suggests, this directory contains all distro specific files, including the ones you will generate for your package.

The source package already has directories for fedora and suse. Now, say you are packaging for Ubuntu. You will first create a new directory named 'ubuntu' as a sibling to fedora and suse, then place all your work in that directory. So, the new layout should look like:


Typically, your distro's directory will contain a convirt.conf file geared to your distro (more on this in Section V.) and any pre- or post- installation scripts you may require for package deployment.

Deployment Layout

As one might suspect, the source package's file structure differs considerably from that of a fully installed package. Here is a typical deployment mapping. You can use this as a guide to install the files in the appropriate locations for your distro.

FORMAT: loc in src package --> loc in deployment env. (file permissions)

Directories: (don't forget to create them first)

/doc/*			-->	/usr/share/convirt/doc/		(0644)
/src/*			-->	/usr/share/convirt/src/		(0644)
/image_store/*		-->	/var/cache/convirt/image_store/	(0644)
/appliance_store/*	-->	/var/cache/convirt/appliance_store/	(0644)
/install/*		-->	/var/cache/convirt/install/	(0644)

Individual Files:

install/client/distros/$DISTRO/convirt.conf -->  /etc/		(0644)

Critical File Permissions:

/usr/share/convirt/install/client/ConVirt		(0755)
/var/cache/convirt/image_store/*/		(0744)
/var/cache/convirt/src/convirt/core/appliance/*/	(0744)


- create a symbolic link:

 /usr/bin/convirt --> /usr/share/convirt/install/client/ConVirt



ConVirt uses a consolidated configuration file called convirt.conf for critical information about the deployment and the host environment. As mentioned in Section III., you are responsible for providing this file fine tuned for your distro under your distro's directory.

NOTE The easiest way to do this would be to copy one from an existing distro's directory and modify it to suit your environment.

Most of the entries in convirt.conf are fairly self explanatory and aren't expected to vary from distro to distro. However, a few merit some comments:

  • PATHS/exec_path: As the name suggests, this is the PATH variable setting

for all shell commands executed by ConVirt. Make sure it is set so the following executables are reachable on your distro:

- lvcreate/lvremove/vgs (the LVM executables) - xm, xentop (the xen management tools) - uname (system info)

  • CLIENT CONFIGURATION/html_browser: Set this to the executable ConVirt

should launch to view the html help documents.

  • Image Store

Since v0.5, convirt has had the ability to provision pre-packaged virtual machine images through the Image Store feature. The source package contains a few default images; however, we highly recommend you consider packaging a provisionable virtual machine image appropriate to your distro. For more details, please see the 'Image Builders Guide' available under the /doc directory.


As mentioned throughout our documentation and on the project website, we are relying on community involvment to create the widest possible packaging coverage in terms of distro's supported. We hope that this document would help us achieve that goal.

If you are interested in creating and/or maintaining a distros pecific package, please get in touch with us via the mailing list/forums/developer emails. Once we know about your interest/contribution, you can expect the following process:

1- A pre-release source package will be delivered to you in enough time to allow repackaging and a coordinated release on all platforms.

2- You will return a revised source package that'll include all your changes for the release under the /distro/$YOUR_DISTRO directory, and a pointer to wherever your downloadable package is located (if you need help with staging your package, please let us know ... we'll be glad to stage it for you).

3- Upon release, the publically available source package will contain your contributions. The main download page at the ConVirt website will contain an acknowledgement and a link to a direct download of your package.


At any and all times, we are available for help/feedback/criticism/suggestions. Just visit the ConVirt website ( and drop us a note in the mailing list, the forums or by email.