Fixing a broken Debian package

Last week I tackled another upgrade of Bugzilla on my Debian server. Unfortunately, I found out the hard way that the package that I tried to install (bugzilla3-3.4.7.0-2) was badly broken - I was left with a half-completed installation that simply would not work. I reported the problem but got no response, so I decided to get to the bottom of this and find out what the trouble is. This is not the story of what I found out, but of how I was finally able to fix the problem.

The process can be shortly described like this:

  1. Extract content of the official Debian package file
  2. Examine content and how the installation process works
  3. Edit file(s) to fix the problem
  4. Re-package into a custom package file
  5. Install software from the custom package file

In the remainder of this article, I provide command line examples for each of the above steps, together with a few brief explanatory notes. Note that the article is intended more as a short Howto than an in-depth explanation of how packaging in Debian works. If you want to know more about this subject you should probably have a look at the many Debian developer manuals, especially the Debian New Maintainer's Guide looks promising.

Extract content of the official Debian package file

So how should you go about looking into, and fixing Debian packaging problems? First you will have to examine the content of the Debian package. After you have downloaded the package via apt-get/aptitude, the package file will be stored under /var/cache/apt/archives. For instance: 

osgiliath:~# l /var/cache/apt/archives/bugzilla3_3.4.7.0-2_all.deb 
-rw-r--r-- 1 root root 2784506 2010-07-22 21:47 /var/cache/apt/archives/bugzilla3_3.4.7.0-2_all.deb

A package file contains two sets of files:

  1. The files that make up the actual software to be installed (e.g. Bugzilla)
  2. A set of control files that govern how the software package is to be installed on, or removed from the system

The following commands extract the two file sets from the package file: 

dpkg --extract /var/cache/apt/archives/bugzilla3_3.4.7.0-2_all.deb /tmp/bugzilla3_mine
dpkg --control /var/cache/apt/archives/bugzilla3_3.4.7.0-2_all.deb /tmp/bugzilla3_mine/DEBIAN

Note that the order in which the file sets are extracted is important, because for later re-packaging we want the control files to be placed inside the directory that holds the software directory structure. Also it is important that the sub-directory holding the control files is labelled DEBIAN.

Examine content and how the installation process works

Now the entire package content is ready for a close-up examination. The control files are of special interest, because in a normal system environment you will never see them - they are only used temporarily for package installation and removal. In the case of "my" Bugzilla package, the set of control files looked like this: 

osgiliath:~# ls -l /tmp/bugzilla3_mine/DEBIAN/
total 276
-rw-r--r-- 1 root root    540 2010-07-22 21:32 conffiles
-rwxr-xr-x 1 root root   2129 2010-07-22 21:32 config
-rw-r--r-- 1 root root   1865 2010-07-22 21:32 control
-rw-r--r-- 1 root root 208060 2010-07-22 21:32 md5sums
-rwxr-xr-x 1 root root  10930 2010-10-12 01:21 postinst
-rwxr-xr-x 1 root root   2434 2010-07-22 21:32 postrm
-rwxr-xr-x 1 root root   3265 2010-07-22 21:32 preinst
-rwxr-xr-x 1 root root   1367 2010-07-22 21:32 prerm
-rw-r--r-- 1 root root  29419 2010-07-22 21:32 templates

Edit file(s) to fix the problem

When you find the problem, fix it by editing the files involved. You may also wish to merely add a bit of debugging stuff to understand the broken installation process.

Obviously, if extensive changes to a control file are required you may need to have a deeper understanding of Debian packaging, so please go and read one of the Debian developer manuals mentioned at the beginning of this article.

Re-package into a custom package file

After you have finished editing you can now re-package everything like this: 

dpkg --build /tmp/bugzilla3_mine /tmp/bugzilla3_mine.deb

Note that the name of the package file is not important for our purposes; for instance it does not matter that the file name does not contain a version number.

Install software from the custom package file

The next, and final, step is installing the software from your custom-built package: 

dpkg --install /tmp/bugzilla3_mine.deb

Obviously, if you are still debugging, rinse and repeat until you get everything to work, or you destroy your Debian box :-)