Update contact information
[www.git] / 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-26)</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
113 <tt>ssh</tt> and 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, <tt>ssh</tt> 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<br>
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 <h2>Security considerations</h2>
318
319 <p>
320 Doing everything as root is less than desirable; however, Android seems
321 to have prevented ordinary users from doing things such as resolving
322 hostnames. When I have time, I'd certainly like to fix this properly, but
323 for now, it seems a Debian chroot on Android must be used as root in
324 order to be useful.
325 </p>
326
327 </div>
328
329 <!--#include virtual="/footer.shtml"-->
330
331 </body>
332
333 </html>