These instructions are heavily based on the instructions from CyanogenMod 7 for HTC Desire: http://wiki.cyanogenmod.com/wiki/HTC_Desire_(GSM):_Full_Update_Guide but also some other sites I found along the way, often for other phone models so only parts apply. I also had some direct feedback from various IRC channels.

The following links were useful to me, so I mention in case you want to read some more:
http://forum.xda-developers.com/forumdisplay.php?f=628
http://forum.xda-developers.com/showthread.php?s=ea2964d1e59f99d394ca758037ee6bc1&t=696189
http://forum.xda-developers.com/showthread.php?t=788044

1. Preparations

The first thing that may be of use, especially if you are checking other instructions, is to grab a few version numbers of the rom levels on your phone:

power off, hold vol down and power – get hboot version page, includes radio version
mine was hboot 0.93.0001
and my radio version is 5.11.05.27
hboot version shouln’t matter for unrevoked3 though unless on very new phone like EVO4
You can also check the radio version from “Settings->About Phone->Software information”.
You should see “Basebane version”, mine is 32.49.00.32U_5.11.05.27
The last part of that, after the _, is the radio rom version

2. Rooting your phone

Go to http://unrevoked.com/recovery/ and download the rooting program.

This uses an exploit in the phone to install a new recovery rom, the “clockwork recovery” rom, which can then be used to do complete phone backups and install new roms.

You will need the “usb debugging” enabled on the phone, and the phone connected only to charge, not as disk access or tethering

It is straight forward on linux (run the downloaded file, and follow the instructions on screen), but I believe on windows there are soe extra drivers to install so check the unrevoked site for more instructions if you are on windows. .

I tried unrevoked3 with only 14mb available, and got “internal error: installing package failed”. Getting the space up to 25mb and it worked fine (I just uninstalled the gmail updates)

3. Backup your current OS (nandroid backup)

Reboot into the hboot screen as in step 1 for version numbers, then use use vol up/down to select “recovery”. The power button acts as the “ok” button here.

This boots the clockwork recovery rom which was installed when you ran unrevoked.

Then use trackball to select backup.

This does a complete backup to SD, also referrred to as a “nandroid backup” which should include the system OS, all installed apps and user data.
You probably need as much space as your phone has on internal memory (512mb for desire).
This will take a little while, so do it on power or a full battery.

The backup should appear in your sdcard in /sdcard/clokworkmod/backups/

Then press back and select the reboot option.

4. Backup apps and app data for migration

Why do you need this if you just did a complete backup? Well, when you install the new OS you will be erasing everything from the internal memory, so this backs up your apps so you can install them again, and also the app-data so you don’t lose it all.

I used the free version of “Titanium Backup” but “Astro File manager” has been suggested too, and it looks like “Gemini App manager” can do this as well.
It is pretty straightforward, but see http://www.incredibleforum.com/forum/htc-incredible-hacks/7893-titanium-backup-how.html if you want specific steps.

5. Backup your whole SD card

Ok, maybe I am paranoid, but at this point I plugged in my phone via USB and zipped up the entire SD card onto my computer. This way I have a backup of my SD card, which includes all the above backups, so if anything goes badly wrong I still have the restore files

I had to disable the usb debug mode to get the disk to mount

6. Update radio rom

Before applying the cyanogenmod, or any other, you may need to update your radio rom version.

According to http://wiki.cyanogenmod.com/wiki/HTC_Desire_(GSM):_Full_Update_Guide the version of mine is good enough for CM7, so I didn’t update it.

7. Now install new rom

Installing the mod is straightfowrard (there are instructions in the first link of this page).

Basically download the mod, and google apps if you want it, and drop the zip files in the root folder of the SD card.
Then use the clockwork recovery mod as we did earlier and select “Wipe data/factory reset” to clear the flash (I have seen reports that this may not be required, but as it is such a large change of version numbers, I decided to do a full wipe), then “Wipe cache partition” to clear that too.

Then simply select “install zip from SD card” and install the new mod, and google apps if you wanted it.

Alternatively, you can use Rom Manager to do it as an app.

After the reboot, use your chosen backup program to then restore all your apps and data, however read the next step first as you may find space to still be an issue.

8. Space savings with CyanogenMod 7

After rebooting into the new OS, I had over 100mb free for base image (out of 148mb capacity reported by OS). 83mb free after installing a similar set of google apps from the market.

After then restoring all my backed up apps and data I found out I only had 25mb free, which is only about 10mb better than on the original android 2.2 from HTC.

You will probably find you have to install an app to force apps to install on SD card by default. Note that CyanogenMod 7 has an option to force all apps there by default, but it will put apps with widgets on there, which breaks the widgets.

There is a way to get even more space for apps with CM7:

All you have to do is add an ext4 partition to your SD card and then install “simple2ext” from the android market.

This is a feature only available on the CyanogenMod 7 roms, and allows you to move all apps, app data, and caches to SD card. There is a performance hit for this, but it seems worth it.

I used a microSD adapter to plug in my SD card into my PC and used “gparted” on Ubuntu (a Live CD will do fine) to shrink the current partition and add an ext4 one
without losing data (but you backed up above in any case, right?)

I created a 1GB partition and after installing simple2ext, I set it to move my apps and dalvik cache to the ext4 partition.

After a reboot I now have loads of space for apps to install to, about 80mb free despite installing another dozen apps without bothering to move them to SD.

To help you decide what to move, the Dalvik cache appears to be a binary cache for the Android implementation of Java. There is a performance hit to moving anything to SD unless you have quite a fast card (http://forum.xda-developers.com/showthread.php?t=1175707 recommends minimum class 4, better yet a class 6). Mine is class 2, and I found that moving the application data seems to
cause the phone to be very noticably slower, so it is probably best avoided unless you have a fast SD card.

Moving the Davlik cache did slow things down a little, but mostly only the boot time and first launch of an app. I decided that for an extra 80mb of space that I could live with that (I have also just ordered a new class 6 SD card, so that should help).

Conclusions

Rooting, and modding was actually incredibly simple. It sounds so scary, but I think it is actually very, very hard to mess it up to a point where you cannot just overwrite with a new mod (or your backup) and start again. Once you get to the nandoid backup point you have a very good recovery strategy!

I have loads more space, which is good, because counting the bytes is annoying. I now don’t have to worry about if I have space to install something.

You do lose the HTC apps and widgets, but I found I could live without them fairly easily (I haven’t used peep since I discovered TweetDeck, and that was my most used HTC app). If you miss the clock widget, search for “sense analog glass clock” on the android market, that is a nice replacement for me. “glass widgets” is a replacement calendar widget, which I now actually prefer.

The battery manager in the new rom is awesome compared to the old 2.2 one. It really shows where the battery is going. I think I possibly get longer battery life with this rom too.

I much prefer the android 2.3 native keyboard to the HTC sense one.

There are some niggles – I have a few gui glitches which cause me to reboot the phone every few weeks, but I am hoping they will be fixed in the next stable build (I have not been brave enough to try the nightly builds :-s )

Overall, I quite like the new UI though it did take some getting used to. The fact I dont have to worry about space is the biggest reason I will keep this rom, though it does sound like starburst rom which is much closer to vanilla HTC sense branded android also allows the “data2sd” hack to get more space

ADSL port forwarding

If your box is behind an ADSL modem (and unless you have a professional server and datacentre to put it in, it probably is) then by default the NAT addressing and firewall will mean that you cannot get in remotely to your box. This may be fine if you don’t want anything from the box accessible, but I tend to like being able to ssh in from anywhere, so you need to set up some port forwarding from your ADSL router/modem to get into your box

I wont attempt to describe how your ADSL modem/router config works, you’ll have to read it’s manual, but the ports you probably want are:

ssh 22 – if you want to log from outside your home network with ssh
smtp 25 – if you want your box to be able to receive email
ftp 21 – if you want ftp (though I recommend sftp or scp which use ssh and therefore encrypt your password and data)
http 80 – if you want webpages visible from the internet
https 443 – if you want webpages visible from the internet and want to use https encrypted http

Dynamic DNS

Unless you have a fixed IP address from your ISP, you will probably want some sort of Dynamic DNS system that sets a hostname to have your current IP address. I use http://dyndns.afraid.org as they are free, you can host your own domain there and there are plenty of domains you can use for sub-domains if you don’t want to buy a domain. They provide lots of scripts to help you keep your IP address recorded correctly whenever it changes

Mail

I really want mail configured for delivery, as that is one of the easiest ways to get alerts from your machine (though twitter could be cool too though). If you have a email to smms gateway or smartphone with push email then these alerts can be very fast and direct.

I use exim, not because it is the fastest or most configurable mail system available, but because it is very easy to get configured and running on Debian or Ubuntu. Simply install the exim4 package and the debconf wizard will get you up and running.

sudo aptitude install exim4

The wizard, which can be re-run with the command sudo dpkg-reconfigure exim4-config, asks you how you want to configure exim. Normally you select the first or second option (“internet site; mail is sent and received directly using SMTP” or “mail sent by smarthost; received via SMTP or fetchmail”). Most of the questions come with sensible defaults. If you selected the second option you will get asked what your smarthost for sending mail is, in many cases this is just mail.your.isp or you can use google if you have an account, but it will require authentication which which is a little more complicated to set up.

Next you want to set all email for ‘root’ to forward to you preferred email address.
Edit /root/.forward to look like this

# Exim filter   < <== do not edit or remove this line!

if error_message then finish endif

deliver me@myemail.com

You can test sending email with a simple command line of mail root -s test followed by a message and then CTRL+d. You should get the email at your address set above.

Logwatch

I like to know what is happening on my boxes, and logwatch does a great job at summarising the changes that have happened very day. Install logwatch with

sudo aptitude install logwatch

and it will email root every day with a summary of log changes and other useful info.

As I don’t actually want this information every day, I moved the cronjob for logwatch from daily to weekly with

sudo mv /etc/cron.daily/00logwatch /etc/cron.weekly/00logwatch

so now I get a weekly summary for my box, which is good enough for me

Raid emails

As I use software raid to make my disks a little more redundant (Warning: RAID is not a backup strategy. 2 disks CAN (and sod’s law / murphey’s law says that at the worst possible time they actually will) both die at the same time. RAID simply gives you an extra chance to get a new disk without having to get your data from a backup)

If you use software RAID, make sure your raid config
cat /etc/mdadm/mdadm.conf
has the following lines set appropriately

MAILADDR root
MAILFROM raid@myserver.com

Smart disk monitoring

As I don’t trust disks (and you shouldn’t either, as they will die on you at the most annoying time) I like to have the S.M.A.R.T disk monitoring installed, which does occasional tests on the disks, and can warn you if the disk starts showing bad sectors. If your disk does have bad sectors, it is probably best to replace it pretty soon, though sometimes you can just get a very small set of bad sectors and live with the disk for a long time.

Install smart with

sudo aptitude install smartmontools

and if you have logwatch installed too, then the SMART reports get added to your logwatch summaries (including disk temperatures which can be a good indication of airflow in your box)

Toughening SSH

I found that I had a lot of attempted logins on my box because SSH was open on the default port. One solution is to move the default port, but I am likely to forget to use that port number and just confuse myself… So I started looking at other ways to reduce the risk of having someone brute-force their way into an account.

You can use some really good stuff like fail2ban to take failed logins and firewall that IP off for a while, but I decided that I wanted something even stronger. I disabled password logins completely via SSH! To do this you will need to have created a ssh keypair and set up the public key on your server and make sure it works to log you in BEFORE you disable password logins.

To disable password logins, simply edit
/etc/ssh/sshd_config
and change

PasswordAuthentication yes

to say “no” instead. This will mean that you can never log in with a password, and have to use a ssh key. This will be almost impossible to brute-force, though you do have to keep your private ssh keyfile secure.

As a minimum, you may want to think about setting

PermitRootLogin no

in your sshd config so that the root account cannot be brute-forced, as this is probably the most common account that attempts are made on.

Monitoring with Munin

To keep an idea of how busy the box is, the cpu and ram usage, disk usage and many more things I have installed munin to monitor my servers. Munin logs system activity and automatically creates web-accessible charts of the status of your box. An example is online at http://munin.ping.uio.no/. I have set mine as password protected via an apache htaccess file with htpassword (there are plenty of resources online for how to do this), so that only I can see how busy my box is.

If you also install sensord and lm-sensors then munin can also chart things like fan speeds and temperatures

Security updates

Whether you are running Debian, Ubuntu or any other linux OS, make sure you check how to setup security updates for your distribution and install updates regularly. Having old packages is possibly the easiest way to get your box exploited.

If you don’t like having to remember to install packages you can install cron-apt to download the packages and tell you, so you can install them, or even install them for you (however it is generally a good idea to know what is going onto your system before it goes in, just in case anything looks suspicious or might break something)

/etc in revision control

Have you ever made a change to your system config, then realised not long later that it was a bad change, but can’t remember what you did?

Introducing etckeeper. etckeeper is a very clever package that takes /etc and puts it all in git. It can easily be configured to automatically commit every time you install or remove a package, so that all you have to do if you found something in /etc is broken is check the recent changes!

Simply install it with

sudo aptitude install etckeeper

and it pretty much works out of the box (It also supports other code control tools other than git, but the default is git)

Anything Else?

This list is by no means complete, and there are probably many more common tweaks you can do – Please leave a comment if you think of anything else that fits in or anything I might be doing wrong (hey, nobody’s perfect!) as I am always looking to improve how I run my little servers.

If you have several machines and static IP addresses then you can configure syslog to log to across the network, which would be cool as you could have errors logged from a box that has had bad disk crashes and dies and still know why. However I don’t have static IP’s so have not looked into this much

While you can just use something like dpkg-deb to turn the right files into a .deb, this only works for already-compiled files and loses some of the great features about Debian-based systems such as changelogs, so I am only going to describe how to make a full source-format package that is built using the Debian tools

Prereqs

You will want to install a few packages before you go any further – these are very useful helper tools for packaging. Install dh-make, dpkg-dev, debhelper and devscripts

sudo aptitude install dh-make dpkg-dev debhelper devscripts

I chose debhelper here as it is a very powerful and yet often simple way of quickly creating packages. It takes a lot of the slow work away from the packager and does very sensible default things. My example package does not really need compiling so it could be simple to just create it by hand, but using debhelper to do the default packaging rules gives you more time to do other things

It is worth mentioning here that all aspects of the parts of a Debian package are covered in detail in the Debian Policy document (http://www.debian.org/doc/debian-policy/, which although Debian specific will not steer you wrong for getting started with Ubuntu packages (the Ubuntu Policy Manual appears to be athttp://people.canonical.com/~cjwatson/ubuntu-policy/policy.html/). (The Policy is also packaged up in the package debian-policy, though ubuntu-policy might be of interest too)

Lets Begin

So, where do we start. Let’s start at the point where you have a simple program, perhaps a shell/perl/python script that you simply want to package up as a deb for easy installation. The first thing we want to do is make a folder formed out of the package name and version, and put the script in it in the correct place.

Here is my example folder with me example program (called simple-program):

simple-package-0.1/usr/bin/simple-program

Note that the folder is the package name followed by a hyphen and a version number (simple point versions are the easiest to work with, so stick with them if possible)

Now, all work is done from within the package folder normally, so cd into that folder

cd simple-package-0.1

So far, all we have is just a folder with a binary in the place we want it to end up in. Now we have to “Debianise” (or Debianize if you prefer) this into a package

dh_make --single  --createorig

This command takes a source tree and turns it into a Debian source package format. The first flag tells dh_make that our source package is only going to build a single binary package (which is the most common). The second argument tells it that we do not have a tarball of our package so it should create a new one for us.

Now if you look in the current folder, you will see a debian/ folder. This is where all the Debian-specific magic happens.

The next thing we do is edit debian/rules

The rules file is the main makefile (or build script) which is run by “make” to produce your package. Everything starts from here.
(If you have a new version of dh-make, then your rules file may already look like this, if your dh-make is older then you will end up with a longer file, so edit it to look like this )

$ cat debian/rules
#!/usr/bin/make -f
# -*- makefile -*-
# Sample debian/rules that uses debhelper.
# This file was originally written by Joey Hess and Craig Small.
# As a special exception, when this file is copied by dh-make into a
# dh-make output file, you may use that output file without restriction.
# This special exception was added by Craig Small in version 0.37 of dh-make.

# Uncomment this to turn on verbose mode.
#export DH_VERBOSE=1
%:
        dh $@


Note that on the last line, the indent is a TAB character. Make sure you use a tab and not several spaces, as make is very particular about tabs

This debian/rules is really simple – all it does is says “whatever I was asked to do, tell the command ‘dh’ to do it instead”. dh has sensible default rules, and you can find more about dh by running the command “man dh” to look at it’s manpage

(If you ever want lots more detail about what each step of building is doing, you can uncomment the line “export DH_VERBOSE=1″ and each helper script will print out more info)

As the above build file doesn’t say anywhere which files to copy to the output package, we have to do something to make that happen. We are going to use the debhelper script called dh_install  to do this.

Edit a new file at debian/simple-package.install

dh_install looks for this file (actually, it will also look for just debian/install) and will copy any files listed in it into your package. In this file we will put a list of files we want installed, one per line (wildcards work too, but I will list our only file for explicitness)

$ cat debian/simple-package.install
usr/bin/simple-program

Notice that we do not have a leading ‘/’, this is deliberate. Also, if you check man dh_install then you will notice that dh_install will not move files to other directories as it is expected that your makefile will do this for you. For now I will assume that your simple package comes with all the files in the correct places.

Building

Now let’s try building. Run dpkg-buildpackage and this will turn your little folder into a Debian source package and then go and create a .deb (It is worth mentioning that the command debuild is also available, but as it is a wrapper around dpkg-buildpackage and other tools I will write more about it later, and just start simply with dpkg-buildpackage)

Have a look:

$ ls ../simple-package_0.1-1_i386.deb
../simple-package_0.1-1_i386.deb

See – you have a .deb

Now let’s have a look inside it (this is just converting the file to a tar and then asking tar to list it’s contents):

$ dpkg –fsys-tarfile ../simple-package_0.1-1_i386.deb |tar -tv
tar: Record size = 8 blocks
drwxr-xr-x root/root 0 2010-06-16 18:48 ./
drwxr-xr-x root/root 0 2010-06-16 18:48 ./usr/
drwxr-xr-x root/root 0 2010-06-16 18:48 ./usr/sbin/
drwxr-xr-x root/root 0 2010-06-16 17:41 ./usr/bin/
-rwxr-xr-x root/root 0 2010-06-16 17:41 ./usr/bin/simple-program
drwxr-xr-x root/root 0 2010-06-16 18:48 ./usr/share/
drwxr-xr-x root/root 0 2010-06-16 18:48 ./usr/share/doc/
drwxr-xr-x root/root 0 2010-06-16 18:48 ./usr/share/doc/simple-package/
-rw-r–r– root/root 193 2010-06-16 17:44 ./usr/share/doc/simple-package/README.Debian
-rw-r–r– root/root 178 2010-06-16 17:44 ./usr/share/doc/simple-package/changelog.Debian.gz
-rw-r–r– root/root 693 2010-06-16 17:44 ./usr/share/doc/simple-package/copyright

Notice that your program is listed in ./usr/bin/simple-program, and also that there is a changelog, a readme and a copyright file – I will come on to those later.

So, we’re done? I can just give this to people?

Erm, no… Not really

While you may have a package, you will notice that it is a rather dumb package

$ dpkg-deb -I ../simple-package_0.1-1_i386.deb
new debian package, version 2.0.
size 1730 bytes: control archive= 524 bytes.
303 bytes, 10 lines control
290 bytes, 4 lines md5sums
Package: simple-package
Version: 0.1-1
Architecture: i386
Maintainer: anton <anton@unknown>
Installed-Size: 32
Section: unknown
Priority: extra
Homepage: <insert the upstream URL, if relevant>
Description: <insert up to 60 chars description>
<insert long description, indented with spaces>

See – it really is a but dumb as we have not configured much about it. Lets start fixing that now as we really don’t want to be giving this to everyone in it’s current state

Package control files

Let’s start with the file debian/control

$ cat debian/control
Source: simple-package
Section: unknown
Priority: extra
Maintainer: anton <anton@unknown>
Build-Depends: debhelper (>= 7)
Standards-Version: 3.8.1
Homepage: <insert the upstream URL, if relevant>

Package: simple-package
Architecture: any
Depends: ${shlibs:Depends}, ${misc:Depends}
Description: <insert up to 60 chars description>
<insert long description, indented with spaces>

We will want to edit several of these fields. Of course these are all explained in Chapter 5 of the Debian Policy. The first thing to note is that the first chunk applies to the source package. Here we want to set our Maintainer name and email.
The build-depends are a default guess too, and should be enough for us for now (build-depends is all the packages needed to build this program, which often include any extra libraries you might need or extra tools such as unzip).
Important: As we are using a somewhat new debhelper way of building, and this might not exist on older boxes, we really need the line here that says to use version 7 or newer of debhelper (otherwise someone might try building with only version 6 and it will fail badly)

The homepage is also worth filling in if your package has one, but the whole line can be deleted if not required. The section and priority I will leave you to look up in the Debian policy manual if you want to know more about them, but can be left as-is for now

The second block is all about the binary .deb we want to produce. Note that the Package: section has the same name – This is the default for a “single package” that we asked dh_make to create for us, though you can have more than one block if your source package should produce multiple debs.
The Architecture: fields is worth getting correct. You can put in values like i386 or amd64 if your package will only work there, or if it should compile and work on any architecture you use any. As my package is a simple script-type application, it is actually slightly more special than that and only needs building once and will not need recompiling for any architecture, so I am going to change this to all. “all” has a special meaning, telling dpkg-buildpackage to only compile it once and use that on any architecture.

The Depends: field is also another important field to get correct. This says what you will need installed to actually use this package. So if your package is written in Python, then you want to put the correct Python package name in here (and a version in brackets like “python (>=2.6)“ if your package needs a minimum level of that package. You can also do OR’s if you use a pipe “|”.
The two magic variable depends are filled in by various debhelper scripts and can be left alone (in this case they will end up empty.

The Description: field has a special formatting. The first line is a short description of less than 60 characters, and then after that is a long description where each line starts with a space. If you want to put an empty line in your long description put a space then a period/dot ( “.”) on this line (do not use an empty line). Full explanation is in the Debian Policy.

“Where do I set the version number” I hear you ask… well, I’m coming to that now

debian/changelog

Package versioning is controlled from the debian/changelog file. You can edit this file directly, but it is often easier to use the command dch as it will fill in various fields for you, and can even do simple increments and comments completely from the command line. If you run dch from the main folder of your package it will launch the default editor with a new comment line created for you. If you want to quickly increment the version you can use dch -i and this will do the same, but increment the version number for you first (creating a new changelog entry in doing so).

Let’s have a quick look at a changelog (you might want to look at Section 4.4 of the Debian Policy too)

$ cat debian/changelog
simple-package (1.0-1) unstable; urgency=low

* Initial release (Closes: #nnnn)

— anton <anton@unknown>   Wed, 16 Jun 2010 19:32:10 +0100

A changelog file is a colletion of repeated blocks like the above. The first line of a block shows the package name, then the version in brackets, then the release this package was built for and then it’s urgency. The version here is what comes out when we build our package. The release is only really used when uploading a package as the build-systems look for this field to work out where your package should go (in Debian you would have something like stable or testing, whereas in Ubuntu you would use the release name such as lucid or maverick)

Then we have a set of specially formatted bullet points. You can have many of these, but check the policy for allowed formatting. Notice that we have a Closes section here. This is used by bugtrackers that are attached to the package building systems, and unless you are uploading to one of these is probably simplest to remove.

Then we have the signature line which should have your name and email address, followed by two spaces and a timestamp. If you use dch -i then dch will create all this for you, and if you check the man page for it you can see how to set environment variables in your shell so that you do not have to tell it your correct name or email address. (It is worth mentioning the -v flag to dch. This lets you set a specific version to be put in the changelog, which is useful when you want to go up to version 2.0 or similar.)

It is perhaps worth mentioning that there are two types of source packages.

The usual type of package has version numbers that have a hyphen in them and the part before the hyphen is the upstream number, and the part after is the Debian revision. This is used to show that the upstream code has a specific version number but allows us to have our own incremented versions that clearly show that we are not shipping a new version of the upstream code but merely patches or even just packaging fixes which do not change the upstream code at all.
When built, these types of packages output a .orig.tar.gz file and a .diff.gz file. This allows the upstream code only to be in the orig.tar.gz, and the diff.tar.gz to be a diff file of all the changes we have made, including the entire contents of the debian/ folder

The second type of package is a “native Debian” package. This package has simpler version numbers and only builds a .tar.gz file. This format is normally only used for packages that are entirely owned by Debian (or Ubuntu) and the source code was created entirely for use in Debian (or Ubuntu).

You can choose which type of package your’s is by how the version number is structured. Without a hyphen it will be a “native” package, however I recommend you use the first type by default (you can also force the type with flags to dpkg-buildpackage).
The advantage of the first type of package is that because you have a .diff.gz and a .orig.tar.gz if you are uploading a very large package you only need to upload the .orig.tar.gz if the code in it has changed. If you are just making packaging fixes, or small patches then these are all in the .diff.gz and will be a much smaller upload.

Other files

Of course there are many other files in debian/ which are mostly templates created by dh_make. I will only explain a few here as they are all pretty well covered in the Debian Policy

debian/copyright – You should put a full license in this file so that people know what license your code is under (see Section 12.5 of the Debian Policy manual)

debian/README.Debian – This file is a readme file that is normally used to supplement any upstream readme file. It is copied out to /usr/share/doc/package-name/ as you saw above in the .deb. It should explain anything you have to do to make this package work that may be different from the upstream readme (if any) and normally contains the “Debian way” of getting your program running.

debian/compat – This file sets the compatibility level of the debhelper tools – you normally don’t need to change this

debian/package-name.dirs or debian/dirs – This file will create empty directories that your package might need. Note that you rarely ever need this as dh_install will create any directories that will be needed to hold the files it copies (I mention this as I frequently see it being used unnecessarily)

debian/preinst, debian/postinst, debian/prerm, debian/postrm – These files (also can be done as package-name.preinst) are the Pre and Post install/remove scripts. I won’t talk much about them now as you shouldn’t need to use them in simple packages. Note that dh_make creates some .ex files as example scripts. As usual see the Debian Policy if you need these

debian/docs – This file lists any doc files you want copied into the /usr/share/doc/package-name/ in your package. It works like dh_install but see the manpage of  dh_installdocs for more information

That is probably all the interesting files for now, you can probably remove all the other files as they are simply template or example files.

Other build output files

You might have noticed that when you built your package, as well as the .orig.tar.gz, the diff.gz and the .deb you also got a .dsc file and a .changes file.

The .changes file is used to describe this version of your package, and contains the latest chunk of your changelog. It also is used by tools such as dput to describe which files to upload and contains the checksums/hashes of these files. This file is usually signed with gpg to prove that this package was built by you.

The .dsc file is kind of similar, except it is purely about the source package. It has the checksums of the source files and is also signed. It also contains details such as the build-dependencies of your package so that systems can use it to work out what needs to be installed to build your package correctly.

You will probably only need either of these files if you are uploading files to some sort of repository, as they are mostly consumed by other programs.

If you try getting the source of a package, try apt-get source hostname then you will see that this downloads the .dsc file, and the releveant source files. If you want to unpack the source, you can use dpkg-source -x *.dsc (or if you want to build the binary package straight away, try apt-get -b source hostname and it will download and build though you might need to run apt-get build-dep hostname to install all the build packages needed for the hostname package)

Advanced building

So you can now create a simple package, you know how to set all the control files and how to increment the version in the changelog (hopefully using dch). Let’s look briefly at some more advanced building with dpkg-buildpackage.

Some packages want to be root to build. What they really want is to feel like they are root, so you can use the program fakeroot to build a package that complains it is not root (this way you don’t actually need root)
$ fakeroot dpkg-buildpackage ….

If you have gpg set up, then you will have noticed that every time you build a package dpkg-buildpackage asks you to enter your passphrase. While this is great for giving the package to others, it can be really annoying if you are doing test builds. The flags -us and -uc (unsigned source, unsigned changes) will stop it asking you.

If you just want to build the source package you can use -S to force that.
Similarly to just build the binary use the -b flag.

If your package is a non-native package, then dpkg-buildpackage will only put the .orig.tar.gz in the .changes file if the version ends in “-1″, otherwise it assumes your .orig.tar.gz is already on the server you are going to copy to (normally using dput). If you want to force it to include the .orig.tar.gz use the -sa flag

One thing worth doing if you do much packaging, is creating a chroot for building in. This way you will know that your build-depends are complete and that if you give the package to someone else (or use another computer) it will definitely build (it is easy to forget all the packages you installed on your box to make it build).

The simplest way to do this is to setup either a pbuilder environment or an sbuild environment, but I will leave an explanation of this for another post.

Enjoy creating your new .deb packages

The disks are as follows: 250G, 200G, 160G 120G, so to get the most space out of them I divided them as follows (Note: this is a simplification for the purpose of explanation, the real disk also has a raid 0, mirrored /boot/ partition which is not mentioned below. You need this because LVM is not supported by GRUB, so you can’t boot from a LVM volume):
250G: A (200G), C (40G)
200G: A (200G)
160G: B (120G) C (40G)
120G: B (120G)

A,B,C are partitions on the disks for software raid – I then set up software raid for each pair of A,B,C and set the created LVM physical volumes on top of them, which then are grouped together into one large volume group, giving me around 360G (actually less once you convert to base 2 rather than 10) of mirrored data storage. Note that I can lose any one disk and still have all my data (though I wouldn’t want to hang around too long replacing the disk as a second disk failing could mean you lose most of your data).

I actually created 3 LVM logical volumes, one for mounting each of / (the root of the disk for all OS data), /home (for all the stuff I actually really care about), and a volume for swap that doesn’t really need to be in lvm or raid, but it was just easier to do.

I previously wrote instructions about how to setup LVM and software raid, but this time round managed to completely screw the whole lot up just near the end. I forgot to define one of the raid devices in /etc/mdadm/mdadm.conf so next time I rebooted this raid device was not found in the early boot stages. As this raid volume is needed to create the full set of LVMs for my root filesystem, the system stopped booting right at the beginning because the LVM array was incomplete.

Fixing it was actually not to difficult, but I mention it here in case it is of help to anyone else (or in case I manage to do it again, which is probably likely)

Fist I booted a Ubuntu Live CD (actually a USB stick image created from my running Ubuntu laptop and a spare Ubuntu CD), but nearly any live cd should do. Once booted, I had to install (in the live session) mdadm and lvm2 as Ubuntu does not have these installed by default. Once you have these tools you can start your recovery (note that this needs to be done with root permissions, so sudo -s or similar to get a root shell)

Find the raid devices with mdadm –assemble –scan and then use pvscan and lvscan as required until your system has found your lvm config, then mount it (don’t forget to mount /boot/ too as we will need to rebuild the initrd)

mkdir /tmp/root
mount /dev/mapper/main-root /tmp/root
mount /dev/md0 /tmp/root/boot
chroot /tmp/root

Now you should be pretty much inside your root filesystem on your lvm array. Now we need to make sure all the raid arrays are configured in /etc/mdadm/mdadm.conf

Run mdadm –detail –scan to generate the lines for the config file, and make sure each array is listed in /etc/mdadm/mdadm.conf

From here it is pretty simple, all we have to do is rebuild the initrd so that it knows how to find all the raid and lvm devices needed during boot. dpkg-reconfigure linux-image-<your current kernel version> It is imporant to make sure that you get the right kernel, so have a look in /boot to check you get the right version (uname -r wont work here because you have booted your live cd image and not the kernel your box will run)

I got several warnings about /proc/ not being mounted, but this did not appear to be a problem.

Reboot, and you should be ok. You may want to make a copy of your current kernel in case you accidentally break it, just copy the linux-image…gz and initrd…gz from /boot/ to new names and run update-grub and that should give you two kernels to choose from (hopefully booting choosing them in the right order, the order should be based on the version numbers in your kernel files so adjust if needed)

If the message below is not verifiable, it is probably mangled by your browser – a plain-text version is at http://strangeparty.com/new_key.txt

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA256,SHA1                                

I have migrated my gpg keys to a stronger key
My old key was:                              

  pub   1024D/B307BAEF 2004-04-22
  Key fingerprint = 116A 5F01 1E5F 1ADE 78C6  EDB3 B9B6 E622 B307 BAEF

and my new key is

  pub   4096R/74B1FA37 2009-11-05
  Key fingerprint = 7401 96D3 E037 2F8F 5965  A358 4046 71FD 74B1 FA37

You can get my key with the following command on linux

  wget -q -O- http://strangeparty.com/anton.gpg | gpg --import -

or by downloading http://strangeparty.com/anton.gpg and importing manually

You can also fetch it from the keyserver with

  gpg --keyserver pgp.mit.edu --recv-key 74B1FA37

If you have my old key, you can verify that I have signed my new one with
my old one with

  gpg --check-sigs 74B1FA37

If you are paranoid and want to check you have downloaded the right key,
you can check the fingerprint of the key against the one above with

  gpg --fingerprint 74B1FA37

If you are completely satisfied, you may want to sign my new key

  gpg --sign-key 74B1FA37

If you do sign me key, please either email me that signature (email the
output of the following command to anton@piatek.co.uk)

  gpg --armor --export 74B1FA37

(Or the following if you have a mail client on your box)

  gpg --armor --export 74B1FA37 | mail -s 'OpenPGP Signatures' anton@piatek.co.uk

Or you can just get gpg/pgp to upload it direct to a keyserver

  gpg --keyserver pgp.mit.edu --send-key 74B1FA37
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.9 (GNU/Linux)

iQIcBAEBCAAGBQJK9r5vAAoJEEBGcf10sfo3mosP/3SvPGY5Rh3swpPsIk6MhM8c
1I9FqFDdwKDdzVg1BR3YMo3UXY6zE/LpBzr63s1CtdUZTbVrm8fuav9CSgdk+PUj
f04ssi5LHrBTY9X7QYF/wgL8skE4ByHf4QGEMR5lfBi8vl35OHaf0yhXXmypKxuV
+f3keX0gpcWrcdn7JKva4J4CJ617QsfNnR/EFQXBBYiwPYkWRSMkSLT6JOO7Y6FY
WPbI+Me2kOe6nlNHx/4OTg7ev9kkIV2Y+dgOQcZIEF6WBL51DzvR4AZApih00Ny+
qD3Hpo+kDSSB6PGKOMVxYbHvFAdwQjQTiptTnsu2TX+0hQypQlrGRvEKXSUg5dn6
HO6AHkfeZ+J3WUfhQVQHHNIdSPT8mpRBLR24INsI8sxtxe9EQezjUJOYKc/BhMY8
n9H1dIdAMtrdz+fFG7cqXsYMY8xs3zUZMa/nyu4uKobLtuUnItRS09Zhqxk51C0k
hqRIEvJybk5i9B9ytUT3zRSQrTL9aLEaJGHq1CcE64ABCLXt8QixSB+60EfR3MVT
otBflmiLaV5UE0x98GZ/JtLTRHKj/vR28/45vhWXSEAJO3A6t3A9qmfg2/YP/vWc
ddFpgK7kDFcQu4hvPzEKWwZUnw9jzP50msjr5Vpcn4/FS7zGPFaPmCWC4h22yxhL
h1aBCg2ijxrHwHDxT3QWiEYEARECAAYFAkr2vm8ACgkQubbmIrMHuu/v2QCePQud
lf4D6cZqvJMHGwv3mvm/I5wAnjSFS4Y2l8OUzCjeZOgTeVGjAMeU
=cmth
-----END PGP SIGNATURE-----

If possible, use the Torrent download: http://releases.ubuntu.com/9.10/ubuntu-9.10-desktop-i386.iso.torrent (it should be faster and saves money for all the mirrors)