Documentation/admin-guide/init.rst

   1 Explaining the "No working init found." boot hang message
   2 =========================================================
   3 :Authors: Andreas Mohr <andi at lisas period de>
   4           Cristian Souza <cristianmsbr at gmail period com>
   5
   6 This document provides some high-level reasons for failure
   7 (listed roughly in order of execution) to load the init binary.
   8
   9 1) **Unable to mount root FS**: Set "debug" kernel parameter (in bootloader
  10    config file or CONFIG_CMDLINE) to get more detailed kernel messages.
  11
  12 2) **init binary doesn't exist on rootfs**: Make sure you have the correct
  13    root FS type (and ``root=`` kernel parameter points to the correct
  14    partition), required drivers such as storage hardware (such as SCSI or
  15    USB!) and filesystem (ext3, jffs2, etc.) are builtin (alternatively as
  16    modules, to be pre-loaded by an initrd).
  17
  18 3) **Broken console device**: Possibly a conflict in ``console= setup``
  19    --> initial console unavailable. E.g. some serial consoles are unreliable
  20    due to serial IRQ issues (e.g. missing interrupt-based configuration).
  21    Try using a different ``console= device`` or e.g. ``netconsole=``.
  22
  23 4) **Binary exists but dependencies not available**: E.g. required library
  24    dependencies of the init binary such as ``/lib/ld-linux.so.2`` missing or
  25    broken. Use ``readelf -d <INIT>|grep NEEDED`` to find out which libraries
  26    are required.
  27
  28 5) **Binary cannot be loaded**: Make sure the binary's architecture matches
  29    your hardware. E.g. i386 vs. x86_64 mismatch, or trying to load x86 on ARM
  30    hardware. In case you tried loading a non-binary file here (shell script?),
  31    you should make sure that the script specifies an interpreter in its
  32    shebang header line (``#!/...``) that is fully working (including its
  33    library dependencies). And before tackling scripts, better first test a
  34    simple non-script binary such as ``/bin/sh`` and confirm its successful
  35    execution. To find out more, add code ``to init/main.c`` to display
  36    kernel_execve()s return values.
  37
  38 Please extend this explanation whenever you find new failure causes
  39 (after all loading the init binary is a CRITICAL and hard transition step
  40 which needs to be made as painless as possible), then submit a patch to LKML.
  41 Further TODOs:
  42
  43 - Implement the various ``run_init_process()`` invocations via a struct array
  44   which can then store the ``kernel_execve()`` result value and on failure
  45   log it all by iterating over **all** results (very important usability fix).
  46 - Try to make the implementation itself more helpful in general, e.g. by
  47   providing additional error messages at affected places.
  48