Linux Installer

Table of Content

  1. Introduction

    1. Aims of project

      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).

    2. Why ?

      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.

    3. History

      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.

    4. Supported systems

      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.

  2. Warnings

    1. Our product is dangerous

      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.

    2. This software can destroy your phone

      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.

    3. Nothing worth a good backup

      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) :

      • your internal user /data partition, holding your user data files
      • your SD-card, if inserted in your phone
      • your ROM, even if it is mounted read-only (normal state)
      • network storage places if the phone is configured to access Samba or NFS (your servers are safe if the phone did not mount them)
      • online backup places like your Google account (we hardly see how it could happen, but it can: your Google account can be altered)

      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 :)

  3. Downloads and documentations

    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.

    1. Downloads

      1. Introduction

        Here are many alternatives to install LinuxInstaller on your Android device. They can be used either for an initial installation, or for an update.

      2. Via the Market from your computer

        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.

      3. Via the Market from your phone

        If you are reading this page on your Android device, click on this link, and ... you know where to click next :)

      4. Via SMS

        TODO: Did not found yet how to create an sms: HTML tag that would support passing a body :/

      5. Via barcode

        Scan one of these codes using any Barcode Scanner.

        Market direct link:
        market://search?q=pname:com.galoula.LinuxInstall
        Browser HTTP link:
        https://market.android.com/details?id=com.galoula.LinuxInstall

        Images generated with Note Everything

      6. From this website

        You can find fresh and old versions of the package on our local backup folder. These files all contain the Market compliant signature.

    2. Documentations

      The Quick Tutorial shipped in the application can be found here.

    3. Changelogs

      Old versions of the package can be found here.

      1. Linux Installer v3.5

        Release date: October-November 2011.

        Author: Gaël Perron.

        • added environment remover
        • added aptitude clean button
        • fixed bugs in the screen locker in the Distribution manager
        • removed unavailable packages from installation lists

      2. Linux Installer v3.4

        Release date: end September 2011.

        Author: Gaël Perron.

        • added more root methods
        • fixed Apache lock issue

      3. Linux Installer v3.3

        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.

        • added more root methods (ways for the app to gain root ID=0)
        • fixed issue of /data and /sdcard wipe on APK removal when chroot was mounted: the default chroot directory is not in the APK /data subfolder anymore
        • added directory method (almost untested ATM)
        • started debugging of block (non loop) method
        • complete redesign of all menus
        • fixed several dozen app crash cases
        • complete rewrite of the English translation (English is now the base language for the application; you are welcome to contact us if you want to translate into any language; including French ... French part have not been maintained, and must re-translated from English. A language is a 300 line XML file)
        • improved the console log
        • added logcat to logs
        • added mail feature from console
        • added many security and sanity checks
        • added internal Quick Tutorial
        • added screen saver lock to prevent system to go in sleep mode during installation
        • added linuxchroot renaming feature
        • added linuxchroot entry script
        • fixed more than a dozen linuxchroot exit issues, and umount failures
        • bogus internal console-terminal have been removed. It may come back in far future.

        InstallerActivity (the free part that let's you install the base debootstrap) is now considered as stable.

      4. Linux Installer v3.2

        Release date: July 22nd 2011.

        Author: Gaël Perron.

      5. Documentation

        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.

      6. Quick tutorial

        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.

  4. Screenshots

    1. Official screenshots

      TODO

    2. User screenshots

      1. Boris Veytsman

        Hmmm

    3. Requirements

      1. Required configuration

        • any computer-like device with Android 1.2+ installed (versions 1.2 to 2.3.4 are known to work)
        • rooted device (the software needs to get root acces via either su, or SuperUser; software need to have UID 0 )
        • at least 300MB free space (preferably 500MB)
        • ext2/ext3/ext4 support (at least one of them, on kernel side) (optional, only if you use a block mode, either loop or not; not required for directory method)
        • loop support in kernel (only for loop method; not required for block or directory)


        Our software ships Busybox and chroot in.

    4. Quick installation guide

      1. The loop method

        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.

        1. make sure you installed the *optional* dependencies (SuperUser (almost mandatory; tested with v3.0-b3), ConnectBot or adb or any other local shell system).
        2. go in Setup menu
        3. leave the default settings about installation in block and loop in the first section (Installation type)
        4. look at the 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.
        5. look at the 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)
        6. look at the loop file size (500 by default; 300 strict minimum; as much as you want if you have room)
        7. leave the other parameters as they are (do not use BLOCK mode without loop mode, do not change any setting in the CONFIGURATION section; misuse of those settings can lead to where you don't want to go)
        8. exit (or back)
        9. click create target loop (takes 2mn to write 500M on class 4 card)
        10. click format target loop (50s)
        11. click mount loop
        12. click 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.
        13. click Update launcher script.
        14. You can now connect to your phone using any local console, via ConnectBot or adb shell
        15. type linuxchroot in this console
        16. you are now in a standard GNU/Debian environment, created via debootstrap. Network is already configured; you shall type aptitude update, then you can install any package you want.
        17. Read messages carefully, and read the full tutorial on our website. URL is given in the About pop-up

        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.

      2. The block method

        WIP . TODO

      3. The directory method

        WIP . TODO

    5. Details of the Setup menu

      Entries of this menu are sorted by category.

      1. Installation type

        TODO

      2. General distribution configuration

        TODO

      3. Loop configuration

        TODO

      4. Block configuration

        TODO

      5. GUI configuration

        TODO

      6. Package software configuration

        TODO

        1. Send debug logs

          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.

        2. TODO

          TODO

    6. UNIX daemons

      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

  5. Installing in a Loop

    1. WHIP

      This is the preferred and most tested method. TODO

  6. Installing in a normal block device

    1. WIP

      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

  7. Installing in a legacy directory

    1. WIP

      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 :)

  8. Using the environment

    1. LinuxChroot, the launcher script

      (or whatever you called it)

      1. Entering LinuxChroot

        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.

      2. Exiting LinuxChroot

        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.

      3. Automated start

        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.

    2. The package

      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.

    3. SSH

      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:

      • deleted the offending key from .ssh/known_hosts
      • put

                Host MyPhone
                    UserKnownHostsFile /dev/null
                    StrictHostKeyChecking no

        in your .ssh/config file (replace MyPhone by a valid hostname, or fixed IP of your device).

      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.

      • access your phone via SSHDroid
      • enter the chroot env
      • install the screen tool
      • start sshd manually
      • check sshd is working properly, and ignore any error message about port already in use, or configure it to start on a free port (different from 22)
      • if sshd starts properly, and only reports about port 22 already in use, now stop it
      • start a screen cession
      • type: sleep 60 ; /etc/init.d/sshd start
      • exit the screen cession ( CTRL + a then d )
      • shutdown SSHDroid any way you want (via GUI menus, or using kill from the available shell). You can stay in the chroot, or leave it, it does not matter, as long as you do NOT press Y when exiting it.

      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).

  9. Marginal use

    1. Very strange things this package is designed to support

      WIP: TODO:

      1. Compiling Wi-Fi driver

        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 ...

      2. Installing Android SDK

        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.

  10. Out of the box

    1. Removing the package

      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:

      • the chroot directory shall not be in /data/data/com.galoula.LinuxInstall
      • ADVANCED features specific will not be available. This includes automatic start of environment at phone boot, and start of services at environment start. These features are specific to the package GUI.

    2. Installing a second environment

      Basically, installing a second environment can be explained in 4 steps:

      • start the package GUI
      • make sure that the old environment is not mounted or chrooted (the interface must offer you to create loop, format, and mount; if the interface is TODO
      • enter the setup menu, and change the loop device (or block name) if any, the chroot directory, and the LinuxChroot script name. You may also want to change the hostname.
      • return in the main window, and restart a fresh installation using the traditional procedure

      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.

    3. Removing a chroot environment

      APK removal will not remove the chroot environment. This is intentional for two reasons:

      • this package was originally designed to install a complete legacy Linux environment into a separate partition, and allow you to perform dual boot, and let you boot the Linux partition even after completely removing Android, and, why not ... install a legacy Linux distribution like Debian inside the Android partition (instead of Android, after removing Android).
      • using any subfolder of /data/data as chroot directory can easily lead to loss of /data and /sdcard data if the APK is removed when chroot is running; this was getting a very frequent bug, and you can imagine that it is very annoying; /data/data is not anymore the default place for chroot, and that is why Android application manager does not remove the chroot directory when uninstalling our APK

      Chroot environment removal is an easy process:

      • make sure that the chroot environment is not running anymore (this is at the moment not documented if using the directory method).
      • remove the chroot directory (the folder name you entered in Setup, the one that is reminded in the main application interface). The directory will be automatically recreated on application start if you do not remove the package.
      • remove the loop file if you were using the loop method
      • remove the two linuxchroot scripts: 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.

  11. Reporting a bug

    1. Sending internal logs via email from your phone

      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.

    2. Sending logs from your computer

      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)

  12. Known and frequent issues

    1. Su, root, id=0, super user ...

      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.

    2. Ext2, ext3, and other filesystem creation

      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).

    3. Unticking 'loop' unticks 'block'

      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.

    4. LinuxChroot installation directory

      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

    5. Some cancel button complain about various errors

      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.

    6. Some buttons have a strange names with a DEPRECATED prefix ...

      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.

    7. The label of some buttons does not fit the button; I can not read it entirely

      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.

    8. Installation or start of some services seems to fail

      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.

    9. DPKG and APT errors ...

      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 .

    10. Auto start does not always do the job

      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.

    11. Draw chrooted applications inside Android ?

      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 ?

    12. Some packages won't install

      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.

    13. Hostname ...

      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".

    14. Reboot to free memory or not ?

      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) .

    15. Many things do not work in "Distribution management" menu

      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 .

    16. Package complains about missing kernel modules ext2 ext3 and loop ...

      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.

    17. Package complains about missing kernel modules: (/proc/config.gz)->Not Found

      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.

  13. Stupid ideas

    This section will describe random stupid ideas that may help stupid g33ks; those are not tips, and they are DISCOURAGED for average Linux users.

    1. This will brick your box

      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.

      1. Never change a parameter you do not understand

        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.

      2. Never configure anything under /data/data

        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.

      3. Never select a random block device

        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.

      4. Avoid using your SD card

        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 .

    2. Breaking installation process

      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.

    3. Using FAT

      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:

      • commit suicide
      • install any other OS
      • use an NFS server

      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

    4. Emulators

      Although we have not tested our software in any emulator, it should work really fine.

    5. Non Linux, still Android systems

      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.

    6. Non Android systems

      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.

    7. IPv6

      IPv6 is supported by our busybox during installation procedure, as long as underlying kernel has an IPv6 stack.

  14. Contact

    1. Contact

      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 .

    2. Document version

      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 .

    3. Contributions

      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.

      1. EXPORT_DISPLAY

        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.

      2. Spellchecking

        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.

      3. CSS

        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.

      4. Translations

        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.

      5. Pictures

        We will apreciate any picture, or screenshot or success stories :) We will open a gallery as soon as we start receiving some.

      6. Misc

        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.

    4. Contributors

      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