tutorials/debian_on_samsung_galaxy.shtml

   1 <!--#include virtual="/doctype.txt"-->
   2 <html>
   3
   4 <!--#include virtual="/head.shtml"-->
   5
   6 <body>
   7
   8 <!--#include virtual="/header.shtml"-->
   9
  10 <!--#include virtual="/navigation.shtml"-->
  11
  12 <div id="content">
  13
  14 <!--
  15
  16 NOTE TO SELF:
  17
  18 When updating this page, be sure to update the "Last Updated" field below,
  19 AND on the tutorials index page!
  20
  21 -->
  22
  23 <h1>Installing Debian GNU/Linux in a chroot on a Samsung Galaxy S II</h1>
  24 <p><em>(Last updated 2011-11-25)</em></p>
  25
  26 <p>
  27 There are numerous how-tos on the web for installing a Debian chroot onto
  28 a smartphone running Android, but most of them either give you an image
  29 to install on your phone (which doesn't teach you anything) or have you
  30 set up the Debian system on your desktop and copy it to the phone.
  31 Neither of these options appeals to me, so I've done it my own way and
  32 written this document to light the way for others, too.
  33 </p>
  34
  35 <p>
  36 Assumptions made:
  37 </p>
  38
  39 <ul>
  40 <li>
  41 You have an Android smartphone with access to a root shell via SSH. I run
  42 <a href="http://www.cyanogenmod.com/">CyanogenMod 7.1</a> on my Galaxy S
  43 II, but any Android system with root SSH access will do, provided it has
  44 the following utilities:
  45   <ul>
  46   <li><tt>cat</tt></li>
  47   <li><tt>chroot</tt></li>
  48   <li><tt>dd</tt></li>
  49   <li><tt>ln</tt></li>
  50   <li><tt>mkdir</tt></li>
  51   <li><tt>mke2fs</tt></li>
  52   <li><tt>mount</tt></li>
  53   <li><tt>tar</tt></li>
  54   <li><tt>wget</tt> (used by <tt>cdebootstrap</tt>)</li>
  55   </ul>
  56 If you don't have these utilities available to you, you will either need
  57 to find a way of installing them, or else find alternative ways of
  58 performing some of the steps in this how-to. Doing either is outside the
  59 scope of this how-to, but most of these utilities are provided by
  60 <tt>busybox</tt> on my device, so installing <tt>busybox</tt> should get
  61 you most of the way there.
  62 </li>
  63 <li>
  64 You have a reasonably fast and high-capacity Internet connection
  65 available on your Android phone. I will not be held responsible for any
  66 excess usage charges you incur on your mobile Internet package while
  67 downloading Debian onto your phone. ;-)
  68 </li>
  69 <li>
  70 You have a basic understanding of Debian and its packaging system. This
  71 procedure does require manual invocation of <tt>dpkg</tt> if you run into
  72 problems -- if you don't know what <tt>dpkg</tt> is or how to use it,
  73 this method probably isn't for you.
  74 </li>
  75 </ul>
  76
  77 <p>
  78 If not all of these assumptions are true, please don't contact me just to
  79 complain if something doesn't go right for you when following this
  80 how-to. Of course, alternative suggestions are welcome!
  81 </p>
  82
  83 <h2>Preparation</h2>
  84
  85 <p>
  86 The first thing you need to do is install <tt>cdebootstrap</tt> on your
  87 phone. <tt>cdebootstrap</tt> is a tool for bootstrapping a Debian system,
  88 usually from another Debian system, but in this case we'll be doing it
  89 from Android.
  90 </p>
  91
  92 <p>
  93 So, to install <tt>cdebootstrap</tt>:
  94 </p>
  95
  96 <ul>
  97 <li>
  98 Download the <a href="http://packages.debian.org/sid/cdebootstrap-static">cdebootstrap-static</a>
  99 package for your architecture. Both <tt>armel</tt> and <tt>armhf</tt>
 100 packages should work on recent Android phones; if you have an older
 101 phone, you may need to stick with <tt>armel</tt>. I'll be using
 102 <tt>armhf</tt> in this tutorial, but you are free to choose whichever
 103 architecture suits you best.
 104 </li>
 105 <li>
 106 Now, copy the files needed for <tt>cdebootstrap</tt> to work across to
 107 the phone. It doesn't matter where you put them, as long as you can
 108 execute the <tt>cdebootstrap</tt> binary -- so don't put it in
 109 <tt>/mnt/sdcard</tt>, as this is mounted with the <tt>noexec</tt> mount
 110 option. These files are nicely ready for us in a tarball located at
 111 <tt>./usr/lib/cdebootstrap/cdebootstrap_0.5.8+b1_armhf.tar.gz</tt> inside
 112 the package, so you can just pipe the contents of this tarball to ssh and
 113 extract it on the phone. I'm going to put it into
 114 <tt>/data/local/bin/</tt>, because that's already in the default
 115 <tt>$PATH</tt> so I don't have to care about it again.
 116 <code>
 117 $ mkdir /tmp/cdebootstrap && cd /tmp/cdebootstrap<br>
 118 $ ar x /path/to/cdebootstrap-static_0.5.8+b1_armhf.deb data.tar.gz<br>
 119 $ tar xzOf data.tar.gz ./usr/lib/cdebootstrap/cdebootstrap_0.5.8+b1_armhf.tar.gz | ssh root@$PHONE 'tar xzC /data/local/bin/'
 120 </code>
 121 Remember to replace <tt>$PHONE</tt> with the hostname of your phone.
 122 </li>
 123 <li>
 124 Unfortunately, the version of <tt>cdebootstrap</tt> included in the
 125 tarball appears to segfault on Android systems. I don't know why this
 126 happens, but replacing it with the binary provided in the package seems
 127 to fix this issue:
 128 <code>
 129 $ tar xzOf data.tar.gz ./usr/bin/cdebootstrap-static | ssh root@$PHONE 'cat >/data/local/bin/cdebootstrap'
 130 </code>
 131 </li>
 132 </ul>
 133
 134 <h2>Bootstrapping the Debian system</h2>
 135
 136 <p>
 137 Now that you have a working <tt>cdebootstrap</tt> on your phone, you can
 138 use it to bootstrap Debian. First, however, you will need to create a
 139 file system for Debian to live on. It may be possible to create such a
 140 file system directly on the SD card, but as I don't really understand
 141 Android partitioning, I decided not to try this and risk losing data. (If
 142 someone knows of a way to do this, please
 143 <a href="about.shtml">contact me</a> and let me know!) The reason you
 144 need a separate file system for Debian is that Android mounts its own
 145 file systems with options like <tt>noexec</tt>, which would disallow
 146 executing all binaries placed on them (thus defeating the purpose of an
 147 operating system).
 148 </p>
 149
 150 <p>
 151 The easiest way to set up a file system is to simply create a file in
 152 <tt>/mnt/sdcard</tt> and format that -- but beware, if you make this file
 153 larger than 2 GiB, the FAT file system it lives on will complain and you
 154 will lose the image next time you reboot. This happened to me the first
 155 time I tried it, and I hadn't made a backup, so I had to do it all over
 156 again. :-(
 157 </p>
 158
 159 <p>
 160 So, ssh to your phone, and run the following commands:
 161 </p>
 162
 163 <code>
 164 # dd if=/dev/zero of=/mnt/sdcard/debian.img bs=1024 count=2000000<br>
 165 # mke2fs -Fj /mnt/sdcard/debian.img<br>
 166 # mkdir /debian<br>
 167 # mount -t ext3 -o noatime,errors=remount-ro /mnt/sdcard/debian.img /debian
 168 # for fs in /dev /proc /sys; do mount -o bind "$fs" "/debian$fs"; done
 169 </code>
 170
 171 <p>
 172 One last thing you need to do before setting up Debian:
 173 <tt>cdebootstrap</tt> expects the system shell to be at <tt>/bin/sh</tt>
 174 and fails without telling you why if it isn't. Since Android's system
 175 shell is <tt>/system/bin/sh</tt>, you have to appease
 176 <tt>cdebootstrap</tt> like so:
 177 </p>
 178
 179 <code>
 180 # mkdir /bin && ln -s /system/bin/sh /bin/sh
 181 </code>
 182
 183 <p>
 184 Now comes the fun bit, where we actually set up a Debian system. Still on
 185 your phone, run <tt>cdebootstrap</tt> to set up a file system tree in
 186 <tt>/debian</tt>. You may want to tweak the options below; I'm using
 187 <tt>ftp.debian-ports.org</tt> as my mirror because (at the time of
 188 writing) the <tt>armhf</tt> architecture is not yet fully integrated into
 189 the official archive. If you're using <tt>armel</tt>, or if you happen to
 190 live in the future, you can use your normal Debian mirror for this.
 191 Don't forget to replace <tt>unstable</tt> with whichever
 192 <a href="http://www.debian.org/releases/">suite</a> you want to install,
 193 but be aware that (at the time of writing) <tt>armhf</tt> only exists in
 194 <tt>unstable</tt> -- if you want <tt>stable</tt> or <tt>testing</tt>, and
 195 you downloaded an <tt>armhf</tt> <tt>cdebootstrap</tt> binary, you will
 196 need to specify the <tt>-aarmel</tt> option to <tt>cdebootstrap</tt>.
 197 </p>
 198
 199 <code>
 200 # cdebootstrap --allow-unauthenticated -c/data/local/bin/cdebootstrap-support/ unstable /debian http://ftp.debian-ports.org/debian/
 201 </code>
 202
 203 <p>
 204 We have to use <tt>--allow-unauthenticated</tt> because <tt>gpgv</tt>
 205 isn't available to authenticate signatures on Android. This command can
 206 take a while to complete, so go and have a coffee or something while you
 207 wait for Debian to download and install.
 208 </p>
 209
 210 <h2>Fixing broken packages</h2>
 211
 212 <p>
 213 It was the case for me that some packages failed to install from
 214 <tt>cdebootstrap</tt>. Fortunately, it had at least progressed to the
 215 point where a shell and <tt>dpkg</tt> were installed and usable in the
 216 chroot, so now we can leave <tt>cdebootstrap</tt> behind and work in
 217 Debian:
 218 </p>
 219
 220 <code>
 221 # chroot /debian /bin/bash<br>
 222 # cd /var/cache/bootstrap<br>
 223 # dpkg -i *.deb
 224 </code>
 225
 226 <p>
 227 At this point, <tt>dpkg</tt> may run into some problems. As the package
 228 archive changes over time and different people install different suites,
 229 your problems will very likely not be the same as mine, so here's where
 230 your familiarity with the Debian package tools comes in. ;-)
 231 </p>
 232
 233 <p>
 234 The main issue I ran into here was circular dependencies. These can be
 235 fixed by the use of the <tt>--force-depends</tt> option to <tt>dpkg</tt>,
 236 to allow it to install and configure one of the packages in the
 237 dependency loop, so that you can then install the others normally. For
 238 example, I found that <tt>libc6</tt> depends on <tt>libgcc1</tt>, which
 239 pre-depends on <tt>multiarch-support</tt>, which depends on
 240 <tt>libc6</tt>. After running:
 241 </p>
 242
 243 <code>
 244 # dpkg --force-depends --configure multiarch-support
 245 </code>
 246
 247 <p>
 248 this circular dependency was no longer a problem, although there were
 249 other remaining circular dependencies that could be fixed in a similar
 250 way.
 251 </p>
 252
 253 <p>
 254 Once you have resolved a few circular dependencies and want to try again,
 255 it is a good idea to run:
 256 </p>
 257
 258 <code>
 259 # dpkg --configure -a
 260 </code>
 261
 262 <p>
 263 before telling <tt>dpkg</tt> to try installing packages again, as the
 264 shell glob <tt>*.deb</tt> will simply present the packages in
 265 alphabetical order, which is usually not a sensible order in terms of
 266 satisyfing dependencies. <tt>dpkg --configure -a</tt> will make sure that
 267 packages which are already installed (and thus don't depend on any which
 268 aren't installed yet) get configured before those which aren't already
 269 installed (and might depend on installed packages being configured).
 270 </p>
 271
 272 <h2>Installing a standard Debian package set</h2>
 273
 274 <p>
 275 <tt>cdebootstrap</tt> will only install packages with a priority of
 276 <tt>required</tt> or <tt>important</tt>. While this will give you a
 277 powerful Unix-like base system, it doesn't include many utilities that
 278 you would get with a standard Debian system. Once all of your package
 279 dependency issues have been resolved, and everything in
 280 <tt>/var/cache/bootstrap/</tt> is installed, you can use
 281 <tt>aptitude</tt> to install a standard Debian system:
 282 </p>
 283
 284 <code>
 285 # echo 'deb http://ftp.debian-ports.org/debian unstable main' >/etc/apt/sources.list<br>
 286 # echo 'nameserver 8.8.8.8' >/etc/resolv.conf<br>
 287 # aptitude update<br>
 288 # aptitude install debian-ports-archive-keyring<br>
 289 # aptitude install '~prequired|~pimportant|~pstandard'
 290 </code>
 291
 292 <p>
 293 What you choose to install beyond this depends on your wants and needs,
 294 and how you like your Debian. ;-)
 295 </p>
 296
 297 <h2>Initialising the Debian system at boot time</h2>
 298
 299 <p>
 300 I have written a couple of simple scripts to ease getting Debian up and
 301 running. They come in pairs; one of them lives in Android and chroots to
 302 Debian, and the other lives in Debian and gets run after the chroot. You
 303 can find a copy of these scripts in
 304 <a href="http://git.steven-mcdonald.id.au/?p=android-debian.git;a=tree">Gitweb</a>,
 305 or clone the git repository with:
 306 </p>
 307
 308 <code>
 309 $ git clone git://git.steven-mcdonald.id.au/android-debian.git
 310 </code>
 311
 312 <p>
 313 For usage information, please refer to the <tt>README</tt> in that git
 314 repository.
 315 </p>
 316
 317 </div>
 318
 319 <!--#include virtual="/footer.shtml"-->
 320
 321 </body>
 322
 323 </html>