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-126.96.36.199-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:
- Extract content of the official Debian package file
- Examine content and how the installation process works
- Edit file(s) to fix the problem
- Re-package into a custom package file
- 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_188.8.131.52-2_all.deb -rw-r--r-- 1 root root 2784506 2010-07-22 21:47 /var/cache/apt/archives/bugzilla3_184.108.40.206-2_all.deb
A package file contains two sets of files:
- The files that make up the actual software to be installed (e.g. Bugzilla)
- 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_220.127.116.11-2_all.deb /tmp/bugzilla3_mine dpkg --control /var/cache/apt/archives/bugzilla3_18.104.22.168-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
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 :-)