In a nutshell, we want to let you use your phone like an ordinary computer, and run all ordinary Linux applications under Android.
Android is a wonderful operating system, based on the Linux kernel. It may, or not, be considered as a distribution: you can add applications, but a very different way compared to ordinary Linux distributions. Considering the available Linux kernel, and UNIX like environment, we had the idea to use chroot to develop a complete traditional Linux distribution environment.
We mainly target at Debian, but Ubuntu is known to work, and plan working on Gentoo pretty soon.
The general concept is to create a chrooted environment in which you can run classic Linux commands. But, keeping Android behind.
This guide will explain you how to use the package to install a classic Linux distribution, install all ordinary LAMP services (Apache, MySQL, PHP, SSH, Samba ...), and possibly install a second distribution, or keep using your distribution after Android package removal (you do not want to spend your life installing systems, or storing static apps; you want to run systems, and remove useless files).
BECAUSE WE CAN DO IT.
Not a good reason ? ... let me see ...
Because it was easy to do ?
Let me try again :) OK, not that easy; as of today, there is no similar project on Market; the Market is more than two years old, and nobody ever published any Debian or Gentoo Installer.
No; the real reason is that we are lame users. And lame users dislike changes. We, as computer users, were used to Linux systems since ages, and did not felt home in Android. Android is nice, it's working, but it's not what we are used to.
But Android, as a shell, is based on a Linux kernel; so, we are just adding a second shell above this kernel; and the magic tool to do that is simply chroot. And inside this second shell, we feel free like air, and can do even more things than in a normal Android. First, we can use exactly the same applications as on our desktop (vim, Firefox, X.org (yes, we are thinking about it very seriously)), shells (bash, Perl, python), and server services we enjoy every day (Apache, Samba ... will allow you to use your phone exactly like a normal Linux Laptop, sharing files around), or do nasty things we will tell about in a serious public website.
The original project was an attempt on installing Linux in a dedicated partition of the disk, and boot a Linux kernel dedicated to some classic distribution as main system. The project failed for various reasons. An alternative was a second attempt on using bi-processor machines (not bi-CPU, but machines with two independent processors, capable of running two different OS at the same time)
to run simultaneously Android and non-Android Linux. It was again a failure.
The project then became a classic chroot, and was an easy success.
Today, we are packaging this project to make YOU run it on YOUR phone. Phone ... or tablet PC, or ordinary PC running Android, whatever, we don't mind, as long as you love Linux, and feel like Android is not what you are used to.
We can not provide a list of supported devices and systems. The software is written and developed for HTC Dream aka G1, then heavily tested on HTC Desire Z and HTC Sensation aka Z710e, or 4G. We have received success stories on many other HTC and Samsung devices. But we can not guarantee that it will work on YOUR phone, due to minor hardware variations from country to country (and also changes done with time), and differences between various ROMs. The software is tested on several stock ROMs, and LeeDrOiD. The software is designed for Android, and it should/may/could work on any Android device.
Our product is dangerous by nature, in the literal meaning of word. It is powerful, it has power inside, and can do many things, for the good, or for the bad.
We do not mean to destroy your phone. We are warning you that it is very easy to do a mistake, and destroy your phone accidentally.
We, as developers, know how bad it can be for you, and will show you the borders you should not cross; feel free to stay inside, or cross the line. But not warning you would mean that you could accidentally cross the line; it is more honest to tell you what can be done safely, and what is very likely to break your goods.
The software is too much powerful for any hand. Developers themselves can not test the software in all possible combinations; we can only test the main cases, and figure out what could go wrong in some particular cases. We can not test every single feature in all possible situations.
This software can destroy your device; VERY BADLY. To a point where absolutely no g33k or hacker could help you. We, as developers, consider ourselves very lucky to have not yet broken any of our phones to this point. But we how it can be done for sure.
This software needs root access to work properly. Root acces are not mandatory, but makes things a lot easier for every body. Having root access allows to do wonderful things, but this power can be used a bad way. And code can have UN-VOLUNTARY mistakes.
This software plays with devices, directories, and mount points. This is unavoidable.
This software have been tested on our phones, but YOUR phone may be slightly different; usually, it will work just the same way as for us; some times it will not; it will just bug, and you will just uninstall the software, or preferably ... sent us a bug report to help us fixing your phone. Or, it can kill your phone; this never happened for now, but we are fully conscious that it CAN happen.
DEVELOPERS OF THE GALOULA TEAM CAN NOT BE HELD RESPONSIBLE FOR ANY DAMAGE DONE TO YOUR PHONE, OR YOUR DATA.
We do our best to prevent and fix bugs. We are using the less possible rights to let you install your beloved Linux Distribution. But things can go bad.
Nothing worth a good backup.
We will now define what a backup is. A backup is a computer storage where your data are held, in a place where the media is very unlikely yo be damaged.
Misuse, or bug in the phone can alter or delete any kind of data at any place your phone can access. This includes (in decreasing probability) :
You must backup every single data before using our software: absolutely every single bit of your phone.
And the backup should be pushed on some phone-independent media. During development, we have lost many times the content of /data and /sdcard.
If your SD-card is your main backup device, you should make a full backup of it on an other device or computer,
or use a second card to test the software, or just leave the card slot empty.
This tutorial will explain you what can be done safely, and what is dangerous to do. You are responsible for following the rails, or decide to try the advanced features.
Now, let's have fun with Debian :)
The Application Package is 1.5 MiB. The subsequent debootstrap will download around 55MiB on the distribution server for a basic install. Of course, the more you install, the more you need to download.
Here are many alternatives to install LinuxInstaller on your Android device. They can be used either for an initial installation, or for an update.
The package can be installed on your phone via the Market, from your computer: click on this link , make sure you are logged in the Market, using the same account as your main Google Account profile in your Android device, click on the Install green button, and then the Market will automatically upload our application in your Android device.
If you are reading this page on your Android device, click on this link, and ... you know where to click next :)
TODO: Did not found yet how to create an sms: HTML tag that would support passing a body :/
Scan one of these codes using any Barcode Scanner.
Market direct link:
Browser HTTP link:
Images generated with Note Everything
You can find fresh and old versions of the package on our local backup folder. These files all contain the Market compliant signature.
The Quick Tutorial shipped in the application can be found here.
Release date: October-November 2011.
Author: Gaël Perron.
aptitude clean
button
Release date: end September 2011.
Author: Gaël Perron.
Release date: August 25th 2011. Out on Market.
Author: Gaël Perron.
There are so many changes, we could hardly hold a complete list. Loads of bug fixes, and loads of new features.
The Application is divided in two parts: InstallerActivity and ServicesActivity.
Each of them have a Setup menu (InstallerSetupActivity and ServicesSetupActivity).
At the moment, the ServicesActivity is shown as a sub menu for InstallerActivity, but they should be considered as equal parts of the software.
InstallerActivity (the free part that let's you install the base debootstrap) is now considered as stable.
Release date: July 22nd 2011.
Author: Gaël Perron.
Tutorial v 2.0, by Benoît-Pierre Demaine, August 20th 2011, for LinuxInstaller 3.3 ,
is a complete rewrite of the documentation
Tutorial v 1.0, by Gaël Perron, 2010-2011, was written to help users discovering the product.
Quick Tutorial v 1.0, by Benoît-Pierre Demaine, August 20th 2011, for Linux Installer 3.3 , is embedded inside the product as a start point for users who may need offline assistance.
TODO
Hmmm
Our software ships Busybox and chroot in.
This tutorial assumes fresh install of the package, and original default config.
The default config will produce several warnings. We chose the default
settings assuming that you may not have 500MiB free in your user /data, so the loop file is created in /mnt/sdcard .
The interface will warn you when leaving this default setting, because accidentally (or voluntary) ejecting
or mounting the SD card via USB may make the chroot environment go wrong. No data loss is expected outside the chrooted environment.
You can ignore those warnings as long as you do not remove your SD card, or plug USB in "Disk Drive" mode.
If some step fails, retry it twice. If a step fails three consecutive times, quit the application by pressing the back button several times, and restart it. If the same error occurs after restarting the application, please send us a bug report.
Setup
menuInstallation type
)chroot point
( /data/local/mnt/Linux by default; it's created the first time you start the Installer). It's the folder where chroot will be done.loop file
name ( /sdcard/Linux.loop by default ; change it to /data/local/Linux.loop if you want the chroot to not crash when remove SD card)file size
(500 by default; 300 strict minimum; as much as you want if you have room)create target loop
(takes 2mn to write 500M on class 4 card)format target loop
(50s)mount loop
install distribution in loop
. Installation should take between 15 and 50 mn depending on your Internet connection speed, and phone specifications (Flash and CPU speed).
Installation process will temporally disable screen saver so that the phone will stay awake, and Internet connection will not be automatically disabled or put in sleep mode.Update launcher script
.adb shell
linuxchroot
in this consoleaptitude update
, then you can install any package you want.
Setup panel is inaccessible when installation process is running, or when the distribution is mounted.
When installation is completed, it is possible to uninstall the Android package LinuxInstaller, and keep using the distribution, or, install a second distribution alongside. Details are explained on the website.
WIP . TODO
WIP . TODO
Entries of this menu are sorted by category.
TODO
TODO
TODO
TODO
TODO
TODO
Background data collection (if you enabled "Send debug logs") will send to the dev team a short anonymous report about your phone configuration (hardware model, Android version), and which stages ran successfully, or failed. This helps us to determine the most frequent issues, and sort them by device type. This is a light process, uses low network bandwidth, and does not help us fixing issues; only to determine which errors are the more people. TODO: rewrite.
TODO
This menu lists the content of /etc/init.d/ . The services you will tick will be started automatically when the GUI starts the chroot.
If you tick the Auto start
box in Setup, then these services will be started at phone boot time.
You shall tick boxes for all services you have selected in the Classic network services menu, and probably no other line than those.
TODO
This is the preferred and most tested method. TODO
This method is almost the same as loop one; it is safe as long as you select the appropriate device; selecting the wrong block may lead you to bricking phone; all other steps are safe. TODO
This method is discouraged in version 3.3, because we did not test it very much. It may work, or may not work. It should be safe for your /system even when allowing write on Android. But it's slightly more risky for you /data and /sdcard for very complex reasons; data loss, if any, are to be expected on phone reboot, APK removal, and/or chroot env stop. TODO
Basically, you untick "block" in the Setup menu, and perform rest of install like for loop. Before removal of environment, TRIPLE CHECK it's not chrooted: run mount, and search if any system directory is "bind mounted" to the chroot folder. Then, do "rm -rf" on chroot folder. Removal is the dangerous step :)
(or whatever you called it)
The LinuxChroot script can be used in many different ways. LinuxChroot is the default name of the chrooting script; you may have configure a different name in the setup menu.
TODO. Arguments: -q
Linuxchroot does not work the same way as the package. Both, the script, and the package, can mount and umount the environment, but they do not do it the same way. They do not perform the same system sanity checks. Both end up with a mounted, and chrooted environment, and you can do the same tasks afterwards. But they do not work the same way.
The chrooting script can be launched from any local console: ConnectBot, adb shell, SSHDroid (it may conflict with installed sshd, take care to shutdown SSHDroid before you start OpenSSH in the chroot).
Every start of the script will try to mount required devices if any, and chroot in the environment it was configured for. After chroot started, the file
/etc/init.android/rc_enter.sh
will be started before showing prompt.
On shell exit, the script will run /etc/init.android/rc_leave.sh
,
then it will quit the chroot, and offer you to umount the blocks and free the loop devices (if any). You can press any key to just skip this step, and leave the environment mounted and all background process in place.
If you answer Y here, the script will try to kill any process started in the chroot. It is a very difficult task to do, and deciding whether a program belongs to chroot or not is complicated:
it may fail in two ways: either, not kill a chroot process, or, kill a non chroot process. In the first case, consecutive umount will fail, and you are safe; in the later case, the script may kill any Android process,
and kill some random application. We are not doing random kills; but writing a script that will make this decision is very difficult. We are trying to not kill Android applications,
even when they are locking the chroot directory. After successful kill, the script will umount the block, and free the loop. If you are using the directory mode, of course, there is nothing to umount.
Which Android process may lock the chroot directory ? many. It depends on your phone settings. The first case would be if you are using a console, or adb shell, and entered the chroot directory from the Android side; typically
cd /data/local/mnt/Linux
. The other options are the Media-Player daemon, while scanning device for media files, or any daemon which decides to perform a full system scan for any reason.
LinuxChroot script can not provide any kind of automated start at boot time. The environment is designed to be able to run with the package removed. A package is required for Android integration, and send any kind of signal (like Hey we are booting) to the chroot environment. This feature is available only ADVANCED version package installed.
Entering LinuxChroot runs /etc/init.android/rc_enter.sh
automatically.
All users are free to edit this file, and add lines like /etc/init.d/sshd start
in there. Do not forget to add &
if you want the task to run in background.
Do not forget that /etc/init.android/rc_enter.sh
will be run every time you enter the chroot env, even if it was already mounted, and even if you are logged in via an other console.
Starting twice services is usually harmless, but in some case it can break things to run some commands twice. The software can not provide at the moment any kind of protection, or flag about this. Developers are trying to keep the chrooted environment unchanged, as far as possible,
and alter as few distribution files as possible. Users who really need this kind of detection can contact developers for assistance.
If you have installed task managers that are capable to run system scripts or application at boot time, you are free to use them. During configuration, LinuxChroot must not be described as script, but as program. This way, and may be able to start all possible daemons in the chroot ... at phone start. This approach will be mandatory for people who want to uninstall the package, or use several chroots at a time.
I have not ADVANCED version, and do not want to pay; is there a workaround ? YES. To start linuxchroot
at boot time. Here is an example.
On LeeDrOiD 2.2 I have found that my PATH was /sbin:/vendor/bin:/system/sbin:/system/bin:/system/xbin:./
but /system/sbin
did not exists. I created /data/local/bin/
, then mounted /system RW,
and created symlink /system/sbin
pointing to /data/local/bin/
. In /data/local/bin/
I created a file called rc.local
(like in Debian)
and added a symlink from /etc/init.d/99doublehp
pointing to /system/sbin/bin/rc.local
.
I was lucky to find in PATH
a directory that did not exist in /
.
The PATH
can not be changed; I can alter /system
, but PATH is defined in /init.rc
and any change in that file are lost after reboot.
In the end, every time LeeDrOiD boots, it runs /system/sbin/bin/rc.local
which is actually /system/sbin/bin/rc.local
... a file I can easily modify without remounting /system
.
At this point, I remounted /system
RO, and can now edit my rc.local
to call linuxchroot.sh
at boot time. Do not forget to call linuxchroot.sh
by absolute path (which linuxchroot.sh
), and put an
put an &
on end of line, and make the last line or rc.local be exit 0
. You usually need to call linuxchroot
, but in THIS particular case, su will segfault at boot time, and when playing around boot time, and since init-scripts are run as root, you can, and must use linuxchroot.sh
.
If you want to launch commands at chroot start should avoid /etc/init.android/rc_enter.sh
,
and prefer /etc/rc.local
. /etc/init.d/rc.local
service is activated by default,
what will make /etc/rc.local
be executed at start. See details in the UNIX daemons section of this documentation.
The package provides only a limited access to the content of the chroot. The package is not designed to let you use the distribution; it is designed to let you INSTALL the distribution; thus the section Out of the box below.
The package may start the chroot if you have a ADVANCED version, and ticked the box TODO box name. If you ticked this box, the package will start all required services at boot time; phone boot.
Services ticked via the "Distribution management" interfaces will be started only at boot time, or, when starting the chroot via the package. These services will never be started when using the LinuxChroot script.
It is impossible to to start the chroot env from the package GUI without staring these services.
SSH is a special tool. You need it for almost everything.
You are likely to have a different host private key for OpenSSH inside chroot, and SSHDroid if you installed it. We can not provide you any magical solution. You will have to, either:
Host MyPhone
UserKnownHostsFile /dev/null
StrictHostKeyChecking no
If you are customising your phone via ssh, and configuring it via SSHDroid, here is the trick to make a soft switch between SSHDroid and OpenSSH from the chrooted environment.
sleep 60 ; /etc/init.d/sshd start
If you choose to run sshd on an alternate port, you can log in by changing the port number in your client configuration, or adding -p PORT
if using a CLI client (replacing PORT word by the actual port number you configured on the server).
WIP: TODO:
an example of what can be done inside the chrooted end: download some source, build and compile applications, and insmod some home build modules to handle the Wireless card using a better driver than the Android native one ... using your stock ROM ...
Some of users are now working on installing Android SDK inside their phones. This means ... stop developing for phone from computer, and do everything inside the phone or tablet; stop cross compiling, stop emulation: develop the apps directly from inside Android. We are excited to hear about success stories.
The environment is designed to be fully functional after package removal.
To enter the environment, just run LinuxChroot as usual.
There are some limitations to package removal:
Basically, installing a second environment can be explained in 4 steps:
The old environment will still be accessible after running the old LinuxChroot script name. Each LinuxChroot script name will offer access to specific environment, and new script update (from within the GUI) will affect only the new configuration, without altering the old configuration.
APK removal will not remove the chroot environment. This is intentional for two reasons:
Chroot environment removal is an easy process:
rm "$(which linuxchroot)" ; rm "$(which linuxchroot.sh)"
. You may need to remount /system with RW properties if the package could not install it elsewhere, and you ticked to allow write on /system.
Press Menu, Console (wait a moment, it is very long to load),
Menu, Mail, then select either E-Mail or Gmail. All fields are automatically filled (To, subject, attachments); just add a short description where asked.
This is our preferred method for low skilled people.
Do not forget to make a description of what you did, which exact steps you attempted,
and what you saw on screen. The background color of Tux (the small penguin top left of screen) is very important for us (which color, when)
and the messages you can read in the status bar just before the bug occurs. If you don't feel like typing all that on your mobile device,
just send the bug report as is, and write a new mail from your computer ASAP, using the same email account, to
support@galoula.com .
But we need you to send us, first the email via Menu / Console / Menu / Mail ... so that we get the attached log file.
This is the preferred method if you are a skilled developer.
Please run adb logcat
and record output in a file.
If the bug is easy to reproduce, start logcat, make the bug occur, and send us the complete log file.
If the bug is occasional, please run logcat as soon as possible after encountering the bug.
ASAP means, within seconds. One minute later, logcat buffer have been completely flushed out, and there is nothing interesting any more.
For Linux users, this command is very handy to filter only what we care about:
adb logcat | grep -i -e AndroidRuntime -e LinuxInstall > /tmp/ADB_logcat_LinuxInstaller_$(date +%Y-%m-%d_%H-%M-%S)
You may be prompted with one of the following message:
'Your 'su' is not compatible!',
'Your root is not compatible!',
'Could not become root(id=0) !',
'could not find/run su'.
These messages mean that the software could not gain root rights. The package needs to be root to perform some vital tasks; the most important is of course the chroot call.
The software automatically attempts more than 12 different methods; you get an error message if all of them failed.
You can not fix this issue alone. You need to send a bug report, including logcat, and complete description of your device (hardware, and software).
You shall mention any particular installation of su, sudo, SuperUser, or Busybox packages.
You shall also tell if your phone have been chrooted, or rooted, either via temp-root of perm-root, or not; please be explicit on this topic.
This problem is considered as a major issue, and will be put on the top of our list of bugs..
Before reporting bugs about this, please try to install SuperUser, and see if it fixes the issue for you.
The package ships Busybox in; this Busybox includes, amongst other tools, mke2fs, also called mkfs.ext2. This will allow the package to perform mkfs for sure, in any hosting environment.
If you want to use your local mkfs.ext2, you will have to disable the "embedded Busybox" (what may have other side effects).
You can optionally select ext3 or ext4. In those cases, mkfs for those versions must be present in the system.
You can alternatively perform mkfs yourself: after configuration, create the loop using the interface, run manually mkfs the way you want, the click on the mount button. This will work on all block devices, including loop method. You can even create the loop file manually if you want.
We are not doing any restriction in the package, as long as the filesystem is supported by your kernel, via any driver you want (in extreme cases, you may need to manually load the driver).
When I untick the loop option, block option is immediately unticked, and loop line becomes grey. Yes, we know, we designed the interface to do this. This is to prevent people who untick loop from falling back into the normal block mode.
The legacy block mode is the most dangerous, and can lead people to easily brick the phone ... if not paying attention to small details.
If you untick block while loop was ticked, reticking block will retick loop. This is deliberate. So that most people will switch between
To install on legacy block device, you need to untick loop, then, re-tick block.
Location of linuxchroot script is important to know. You know where the script is installed by typing
which linuxchroot
.
The script is not always installed at the same place on all devices, because each device is different.
The normal process will automatically determine where it would be clever to install it. Since normal commands are searched in your PATH,
the application tries to install the script in one of the folder listed in echo $PATH
.
The PATH is parsed twice.
WIP . TODO: dossier ou est cree linuxchroot: expliquer que le $PATH est pris a l'envers
I have entered the Change password window, pressed cancel, and I have got an error message in the status bar. This is a known harmless issue. In fact, no error occurred, but some internal check detected a non-existing error. This will be fixed in version 3.5 .
You will notice that in such a case, the Tux will stay white, and will not turn red; as long as the Tux stays white, you can ignore the message.
Some buttons have a strange name or label, with prefix "DEPRECATED:". Yes, this is more or less intentional. Please send us an email with the exact label you can read, and explaining in which menu you have seen this.
If you found a button where the label does not fit the button, please send us an email telling which part of the label you can read, exactly, and do not forget to mention if you are using your phone in landscape or portrait position. Then, give us your phone model, screen resolution, and ROM version.
After ticking Lighttpd and Samba in the Classic network services list, and clicking Install, I get no particular error, but returning in the menu will show only Lighttpd as ticked, not Samba ... .
Yes, this is a known bug; it will be fixed in version 3.5 . If you had a white Tux after clicking on install, then all requested packages are installed. The GUI misdetects whether some services are installed or not; but if the Tux turned white after installation, then, all selected packages are installed in the chroot env.
You should also know that the package installer is still under development. The Please wait pop-up may not always appear; you should focus on the status bar.
After a successful install, you should get the Success message in the status bar. If you clicked on Install and the status bar did not change,
then you can assume that work is being done in background. Wait a few seconds or minutes, and when command is completed, the status bar will be updated; in the meanwhile, do not switch to any other application, or install may fail completely.
Unticked services will be removed.
I have installed Apache2, ticked apache2 in UNIX daemons list, ticked auto start, but it will not start at boot ....
Apache is known to refuse to start at the moment; we are working on this issue. Manual start of this service will also fail; adding /etc/init.d/apache2 start in /etc/init.android/rc_enter.sh will also fail. You can try lighttpd instead.
I can read some dpkg and, or, apt or aptitude bits of errors in the status bar, or in console logs, what can I do ?.
Typically, the most frequent error message is E: dpkg was interrupted, you must manually run 'dpkg --configure -a' to correct the problem.
You can try to click on the Update apt
button. It usually fixes the issue without having to start any interactive console. Clicking this button will internally always run dpkg --configure -a
.
I ticked Auto start
button, but nothing happens at boot time. Yes, this is know bug; it may happen that the Package will not be able to start Registered services at Android boot time.
It would be natural for most of us to want to run chrooted applications the graphical way. For example, you installed Abiword in chroot, and want Abiword to show up on your Android device. This is actually not supported.
What is not supported, is the use of Android graphical layer (don't know the name, X ? X11 ? not even sure it would be X11R6 compatible).
What you can do is to install a VNC server inside the chroot, and install some VNC client in your device, and use VNC to access your locally-hosted server :) This is untested, but should work pretty easily.
If any of you know how to use directly the X layer of Android, any help or peace of advice are welcome.
An other stupid idea to work on: start a second X server, in a new console. Since we have a Linux kernel underneath ...
it should support multiple consoles. And why not start a new X in a new vt ?
I ticked to install some package, and they repeatedly refuse to get installed; all installation attempt end with an error.. At the moment, the Distribution Manager is in Alpha state. We have put many package names, but we are not testing if these packages are really available in the distribution you selected for installation. We have put names that may be available in some distribution or an other, but may not be available in all distributions. A typical example for this issue is Firefox which may be called Iceweasel in some versions of Debian; only one of those two package name can be available in a given distribution at a time; we have put both name any way. Version 3.5 of the product will probably contain a filter to unavailable packages from lists.
The Setup menu can let you setup some hostname. In various cases, this hostname may be propagated into the Android system. This should be harmless, but, in very special cases, it can induce bugs in other applications. If you have such issue, please report us about it, and change the hostname in your Setup menu; change it to "localhost".
Some forums say you should use task-killers; the old version of this tutorial says you should reboot phone before trying to install a chroot env. This was true, and useful for old versions of Android, but is now false for recent versions. Task killers can even reduce battery life time when they automatically kill tasks in recent versions. Rebooting to free memory, or using task killers is now always a BAD idea. This was changed in Android Froyo (version 2.2), and improved again in Android Gingerbread (2.3) .
Yes, this part is still under development. It's far from stable; we have not yet written all features.
The most important thing you shall know about it is that when you click an "Install" button,
the application will perform some aptitude work in the background, but the GUI will not be locked. It may seem to you that
no work is done, but process are running in the background. After pressing Install, you shall wait for a long time, not exit the application, and not send it in background.
I have a "Stop chroot" button, and all other buttons are disabled. Usually, when chroot is not started, all buttons will be disabled, except one offering you to start the chroot. When chroot is started, all buttons will be available,
and the "Start chroot" button will change label for "Stop chroot". The particular case when you have "Stop chroot"
all alone means that the chroot folder is available, but not populated. It means that you have not run the "Install" process yet.
Just click on back, and then click "Install".
I have installed samba, but the line is not ticked in the "Classic network services" list.. Yes, known bug; will be fixed in 3.5 .
I have installed Apache, but it will not start. Yes, known issue; we are getting this message at the moment, and working on it: [Tue Aug 23 10:11:22 2011] [emerg] (38)Function not implemented: Couldn't create accept lock
I would like to clean apt .... Feature request is on fire; will be in 3.5 .
TODO.
Your kernel may lack modules, OR you have them but the app does not detect them.
Change kernel, or change ROM. In either case, the folder method will work.
TODO.
The message means that your kernel was build without the module providing config.gz .
This is build dependant (and may evolve with time in a given ROM serie: just ask your ROM builder to add this module).
The message is harmless, ignore it.
The message is here for historical reasons. Galoula used to rely on config.gz to probe some features;
it was the easy way; but since many people don't have it,
I forced him to implement run-time-practical tests to see if features are available or not. Since then, this soft probe had become useless.
We are not removing yet this message because we did not proof test yet my new approach: the run-time test are not 100% reliable.
This section will describe random stupid ideas that may help stupid g33ks; those are not tips, and they are DISCOURAGED for average Linux users.
Here we are: "How-to brick my phone". The following actions or choices are known to delete data, wipe things out, or brick the device.
NEVER TYPE RANDOM VALUES IN RANDOM FIELDS of the setup menu.
In case of doubt, if you think you did something wrong, you will need to re-initialise the application profile;
go in the Android application manager, click on LinuxInstaller as if you wanted to remove it, and click Clear data
.
The package GUI does not provide ATM any way to revert to default settings.
Never configure the chroot directory (folder) to be a child directory of any of /data/data/*/ .
This will not immediately do bad things, but will easily wipe phone out. The issue is that if the chroot directory is mounted at the time you are un-installing application foobar owning the subdirectory /data/data/com.foobar ,
Android will try to remove the child directory, and thus, the chroot directory. If you have chosen to activate Android integration, then, your chroot contains links to / , and removing the chroot directory will
recursively wipe /data and /sdcard. Application update is safe; the danger is around application removal. Application removal is safe if you have closed all chroot env (this is easy to detect when using block modes: just type df -h
: links
from chroot directory to Android / will come out; it's way trickier for directory method: even mount may not tell chat's going on). Symbolic links from /data/data/*/ to chroot directory should be fine (untested) (note: I said /data/data/*/ , not /data/data/* ); hard links are not a good idea. Just never mess with /data/data and you will be fine.
If you are messing with /data/data, and mounted network services like NFS or Samba in the chroot directory, application removal may erase the content of the network server.
We currently do not know how if the software can alter data on Google account, but there is a very small possibility it could happen. It could happen if you are messing with symbolic or links hard between the chroot environment, and /data/data, and the chroot env alters local data just before an Android sync. It did not happen yet, but it could.
Do not select a random block device. When selecting a block device (non-loop mode), be very careful to select the appropriate device.
If, for example, you own an HTC Sensation, and select /dev/block/mmcblk0 (main internal FLASH device) as installation block, the first step of installation (aka mkfs) will just wipe out your phone;
not just /data, not just /system, not just RECOVERY partition: your whole phone will go away. This is the most dangerous know possible thing to do.
We are not going to try this on any of our dev phones; maybe you can try this and tell us what is going on if you have advanced development tools from HTC, and understand what it will do, and know you are able to recover from this kind of things.
But we can not filter this kind of choice, because we want to let you able to use /dev/block/mmcblk1 which is the micro SD card ... Doing an automated scripted process to check which block is used for what is just ... a nightmare; we would probably do it the wrong way, and promise for a security that would not be 100.000000% safe.
Just don't be stupid, and check 3 times you are selecting the appropriate device.
We can not filter these kind of things. There are too many differences between phones on market. If we try to filter some of those things to protect some users, we will have side effect, and prevent other users to do safe operations on different phones.
Avoid using your SD card to store your Linux.loop file, or put the chroot dir below /sdcard . If you accidentally remove your sdcard while the environment is mounted, or just plug USB with PC storage mode, you may get unexpected behaviour.
Variations in behaviour will depend on if you are using the Android Compatibility mode or not.
The SD card is still the default storage place for Linux.loop file because we assume that most users will not have 500MiB free in their /data partition; some may not even have 300MiB. But we recommend you to use /data if you can, possibly /data/local/tmp/Linux.loop .
Main installation process now has a Cancel button. It is discouraged to use it. After breaking install process,
reclicking on Install may work if you broke fetch step, but is likely to not be resumable if you stopped it during unpack or install.
Install process will turn the application into daemon mode, so that putting it in background will not pause it. Install will also disable sleep mode (if you did not disable it), to avoid CPU frequency reduction, and network shutdown.
Installation process in the distribution manger is actually unstable in version 3.3. It is fragile, and may bug. After any break, you can press Update apt
and hope it will fix issues, before trying anything else.
Using FAT to run chroot is currently untested. But we plan on supporting it in a few months. There is no issue in having a FAT / ; the issue is in having a FAT / and trying to use the directory chroot method. Both block methods should work on a FAT / (untested ATM; thus should).
If you are locked up with a fully FATed device, you can either:
If you have a device that only supports FAT, please sent us a message, describing what it is exactly, and how it seem to work. We will work on your case.
Having a system based on FAT is not by itself an issue. The real issue is if you have a kernel not supporting ext2 at all. If your environment does not provide mkfs.ext2, just send us a report and we will try to include mkfs.ext2 in our next release. The real issue that would have no solution for us would be if your kernel does not have a read AND WRITE driver for ext2
Although we have not tested our software in any emulator, it should work really fine.
You may have a non Linux Android system. We have not heard of any yet, but it could exist. And our software should work straight away, providing that you meet the previously listed requirements
(standard UNIX API, ext2 support, mkfs, chroot feature in kernel).
In any case, ext2 support is optical; you can do a simple directory chroot.
Some non Android systems may be acceptable as well, as long as they provide the usual requirements, and an Android compatibility layer. We recommend to not try block mode at all, and just try the directory chroot approach.
IPv6 is supported by our busybox during installation procedure, as long as underlying kernel has an IPv6 stack.
Linux Installer is an original idea of Gaël Perron.
Linux Installer v3.3 was written by Gaël Perron.
This documentation is written and maintained by Benoît-Pierre Demaine, aka DoubleHP.
Bugs, issues, and comment about software should be sent to support@galoula.com . Comments about documentation and tutorials should be sent to benoit@demaine.info .
This tutorial is version 2.0, written by DoubleHP, on August 20th 2011, for Linux Installer v 3.3. Latest change on August 25rd 2011.
The base URL of this document is http://android.galoula.com/en/LinuxInstall .
I have free time, I love this software, and I want to contribute and have my name in the list above, what ca I do to help ?
Well, not much. Galoula is the exclusive developer. Doublehp is just a friend who tries to help. Package is written in Java, in Eclipse.
Peripheral scripts are written in shell scripts.
As stated above, there are few points where help would be apreciated. First, every single user who has an issue should report it.
THAT is helpfull to contribute to software quality.
Then, do some researches on how to implement some major features. At the moment, the biggest missing part is EXPORT DISPLAY. Galoula have no clue about how to make the chrooted env send X calls to Android. Android shell does not set EXPORT_DISPLAY env var, and does not know how to make apps running in chroot, appear directly in Android graphical env. We have told about VNC to help YOU get things working, but VNC is a dirty trick; it's not pure UNIX, it's not a real solution. It would help us, and all out users if some one could take time to send us back a resume on how to allow export display from chroot to Android. Or at least tell us about the main lines.
All documents have been checked with aspell, but I have been said there are still mistakes. Within few days, I will complete version 2.0 of this document. When document is pleted, contributions will be welcome to check syntax, phrasing, and spelling. There are three documents to check: this full tutorial, the quick tutorial, and the package language file. The two tutorials are online, and pure HTML. You can just save file from your browser, check file, and send us back your corrections by email. We will then diff, to see what you changed, and if we like the changes, we will merge them. The Package language file (which contains all labels for buttons, and pop-up messages) should be asked for by email. It will not be published. It's not commented yet; I have 2 or 3 days of work on it, to clean it, comment, and check few minor points.
We would also appreciate to see this tutorial a bit updated on the graphical aspect. We would like to change a few details; introduction of CSS would allow to have sub-sections numbers include the number of the parent section they belong to: example: this present section, is called 3, in subsection C, in section 17; we would like to have "CSS" be labeled "17.C.3" instead of just "3". It's basic CSS, it will save us a few hours of google. We would also like to have a complete TOC; actual TOC only contains manually entered sections; CSS should allow to have automatically generated complete CSS, containing all sections and subsections, generated on client side, so that when a section is added in the body of the page, it will be automatically added to TOC when you view it. Again 3 or 4h to save us.
The main language of application is not French anymore; the native language of the app is now English. Every one is welcome to translate the language file to any other language; including retranslation of the French part which is outdated by now. I need to comment the language file to indicate some special things about some special lines; for example, some labels must fit some limited length; some buttons shall have specific words; wome words must be kept non-translated to match tutorial, or interface homogeneity.
We will apreciate any picture, or screenshot or success stories :) We will open a gallery as soon as we start receiving some.
And probably many more small details Galoula did not tell me about for now. I know that having the distribution manager being a sub menu of Installer is not nice; we would need example of code about how to make tabs; not just for two tabs; many more things are planed for the future; we need a tab manager on top of the application, like in Quick System Info, or bottom like in WidgetSoid.
Special thanks to Adam Outler, and to all Android users who send us bug reports.
We also want to express our greatest recognition to the XDA forum, LeeDrOiD, mike1986, Koush, and all people who published softwares and tutorial helping us to use free hardware. And of course, we would not feel the power under our fingertips without High Tech Computer Corporation
This document is the property of Gaël Perron. Copyright © 2011 Gaël Perron