Skip to main content: Skip to navigation
The C Shore
Daniel Dickinson's Website
  Skip to top : Skip to navigation

OpenWRT Boot Sequence - Preinit

A description of the portion of OpenWRT boot sequence that occurs before ‘init’ (multiuser) is executed. (as of 2010-01-08 proposed, not in tree)

Context: Boot Sequence

The basic OpenWRT boot sequence is:

  1. boot loader loads kernel
  2. kernel loads
  3. kernel calls /etc/preinit (the kernel considers this to be the ‘init’ (or root) process
  4. /etc/preinit prepares system for multiuser mode
  5. /etc/preinit execs /sbin/init which becomes the ‘init’ (or root) process and launches multiuser
  6. /sbin/init launches processes according to /etc/inittab.
  7. Typically the first process launched is /etc/init.d/rcS which causes the scripts in /etc/init.d which begin with ‘S’ to be launched (in glob sort order)
  8. These script initialize daemons that wait for input, so that when all the scripts have executed the normal system is active


Preinit brings the system from raw kernel to ready for multiuser. To do so it performs the following tasks:

  1. Mounts essential kernel filesystems like procfs
  2. Initializes device tree (/dev)
  3. Initializes console (serial console if present, otherwise dummy so that the script interpreter works properly)
  4. Presents opportunity for the user to enter a special operating mode called ‘failsafe’ (Failsafe is presented in a separate section as once it is entered it doesn’t exit. A reboot is necessary to enter normal operating mode).
  5. Mounts the root filesystem
  6. If it’s the first time booting after flashing the firmware, and a previous configuration was saved during the flashing process, that configuration is restored.
  7. Becomes (though exec) ‘init’ which goes to multiuser mode


Preinit consists of a number of the scripts. The main script is /etc/preinit which reads in the scripts. The scripts define functions which they attach to hooks. These hooks are, when processed, launch the functions in the order they were added to the hooks.

Currently there are four hooks used by the system:

  • preinit_essential
  • preinit_main
  • failsafe
  • initramfs

These hooks are actually just string variables with the name of each function to be executed, separated by spaces. The hook variables have _hook appended to the hook name. Thus the name of the variable for the preinit_essential hook is preinit_essential_hook.

Main Script

The main script is actually quite empty it:

  1. Initializes some variables (including the hook variables)
  2. Defines the function pi_hook_add, which is used to add functions to a hook
  3. Defines the function pi_run_hook, which executes the functions that were added to a hook
  4. Sources (reads) the shell scripts under /etc/preinit.d, in glob sort order
  5. Processes the hook preinit_essential
  6. Sources (reads) /etc/preinit.arch, if it exists
  7. Processes the hook preinit_main

That’s it.


There are a number of variables that control options of preinit. There are defaults defined in the main script, however in general their value will come from the file /etc/preinit.d/00_preinit.conf which is sourced by the main script, and which is created by the OpenWRT build process, based on values entered via make menuconfig.

The variables defined at present are:

pi_ifnameThe device name of the network interface used to emit network messages during preinit (except failsafe)
pi_ipThe IP address of the preinit network (see above)
pi_broadcastThe broadcast address of the preinit network (see above)
pi_netmaskThe netmask for the preinit network (see above)
fs_failsafe_ifnameThe device name of the network interface used to emit network messages and allow network logins while in failsafe mode
fs_failsafe_ipThe IP address of the failsafe network (see above)
fs_failsafe_broadcastThe broadcast address of the failsafe network (see above)
fs_failsafe_netmaskThe netmask of the failsafe network (see above)
fs_failsafe_wait_timeoutHow long to pause while allowing the user to choose to enter failsafe mode. Default is two (2) seconds.
pi_suppress_stderrIf this is “y”, then output on standard error (stderr, file descriptor 2), is ignored during preinit. This is the default in previous versions of OpenWRT (which did not have this option)
pi_init_supress_stderrIf pi_suppress_stderr is not “y” (i.e. stderr is not suppressed for preinit), then this option controls whether init, and process run by init, except those associated with a terminal device (e.g. tts/0, ttyS0, tty1, pts/0, or other similar devices) will have stderr suppressed (not that network terminals such as those from SSH are associated with a pseudo-terminal device such as pty0/pty1 and are thus unaffected). As with pi_suppress_stderr, the default, and behaviour from previous versions of OpenWRT is “y”.
pi_init_pathThe default search PATH for binaries for commands run by init. Default is “/bin:/sbin:/usr/bin:/usr/sbin”
pi_init_cmdThe command to run as ‘init’. Default is /sbin/init


The following sections describe the files and functions used by the various hooks.

NB: The files, even though divided by hook here are all in the single /etc/preinit.d directory, and are thus combined in the directory lists, and are processed in glob sort order, not by hook (when sourcing them, the hooks specify the order of the execution of functions, which is as listed below)


The preinit_essentials hook takes care of mounting essential kernel filesystems such as proc, and initializing the console.

Files containing the functions executed by this hook

10_essential_fsdo_mount_procfs, do_mount_sysfs, do_mount_tmpfs
20_device_fs_mountdo_mount_devfs, do_mount_hotplug, do_mount_udev, choose_device_fs
30_device_daemonsinit_hotplug, init_udev, init_device_fs

Functions, in order, executed by this hook (doesn’t list the functions only called by other functions)

do_mount_procfsmounts /proc
do_mount_sysfsmounts /sys
do_mount_tmpfsmounts /tmp
choose_device_fsdetermines type of device daemon and the appropriate
filesystem to mount on /dev for that device daemoninit_device_fs
launches daemons (if any) responsible for population/dev, and/or creating hotplug events when devices are added/removed (and for initial coldplug events)
init_shmmakes sure /dev/shm exists
init_ptsmakes sure /dev/pts exists
do_mount_ptsmounts devpts on /dev/pts (pseudo-terminals)
choose_consoledetermines devices for stdin, stdout, and stderr
init_consoleactivates stdin, stdout, and stderr of preinit (and subsequent init) (prior to this they are not present in the environment)


The preinit_main hook performs all the functions required of preinit, except those functions, like console, that are essential even for preinit tasks.

20_indicate_preinitpreinit_ip, preinit_ip_deconfig, preinit_net_echo, preinit_echo, pi_indicate_led, pi_indicate_preinit
40_failsafe_waitfs_wait_for_key, failsafe_wait

Functions, in order, executed by this hook (doesn’t list the functions only called by other functions)

init_hotplugInitialize hotplug, if needed (that is for devfs). Hotplug or a device daemon is needed so that devices are available for use for preinit
preinit_ipInitialize network interface (if one has been defined for as available for preinit)
pi_indicate_preinitSend messages to console, network, and/or led, depending on which, if any, of these is present which say that we are in preinit mode
failsafe_waitEmits messages (to network and console) that indicate the user has the option to enter failsafe mode and wait for the configured period of time (default two seconds) for the user to select failsafe mode
run_failsafe_hookIf user chooses to enter failsafe mode, run the failsafe hook (which at present doesn’t return, which means no more functions from preinit_main get run on this boot)
indicate_regular_preinit_bootEmits messages to network, console, and/or LED depending on which (if any) is present, indicating that it’s a regular boot not a failsafe boot
initramfs_testIf initramfs is present run the initramfs hook and exit
do_mount_rootMount root filesystem (via /sbin/mount_root)
restore_configIf a previous configuration was stored by sysupgrade, restore it to the rootfs
run_initExec the command defined by pi_init_cmd with the environment variables defined by pi_init_env, plus PATH pi_init_path


Do what needs to done to prepare failsafe mode and enter it.

10_indicate_failsafefailsafe_ip, failsafe_net_echo, failsafe_echo, indicate_failsafe_led, indicate_failsafe
99_10_failsafe_loginfailsafe_netlogin, failsafe_shell

Functions, in order, executed by this hook (doesn’t list the functions only called by other functions)

failsafe_ipInitialize network interface (if one has been been defined for use in failsafe mode
indicate_failsafeEmit message/status to network, console, and/or LED (depending on which, if any, are present) indicating that the device is now in failsafe mode
failsafe_netloginLaunch telnet daemon to allow telnet login on the defined network interface (if any)
failsafe_shellLaunch a shell for access via serial console (if present)


No files or functions at this time.

[Icon for Best Viewed with Any Browser Campaign]
[Valid XHTML 1.0 Strict icon]
Generated by
Friday, January 08 19:11:10 EST 2010
Skip to top : Skip to main content

This page Copyright 2010 Vertical Communications. See Copyright and licensing information for information on how you can use this document.

Last modified Fri Jan 08 19:10:33 -0500 2010.