Home | History | Annotate | Download | only in init
      1 
      2 Android Init Language
      3 ---------------------
      4 
      5 The Android Init Language consists of four broad classes of statements,
      6 which are Actions, Commands, Services, and Options.
      7 
      8 All of these are line-oriented, consisting of tokens separated by
      9 whitespace.  The c-style backslash escapes may be used to insert
     10 whitespace into a token.  Double quotes may also be used to prevent
     11 whitespace from breaking text into multiple tokens.  The backslash,
     12 when it is the last character on a line, may be used for line-folding.
     13 
     14 Lines which start with a # (leading whitespace allowed) are comments.
     15 
     16 Actions and Services implicitly declare a new section.  All commands
     17 or options belong to the section most recently declared.  Commands
     18 or options before the first section are ignored.
     19 
     20 Actions and Services have unique names.  If a second Action or Service
     21 is declared with the same name as an existing one, it is ignored as
     22 an error.  (??? should we override instead)
     23 
     24 
     25 Actions
     26 -------
     27 Actions are named sequences of commands.  Actions have a trigger which
     28 is used to determine when the action should occur.  When an event
     29 occurs which matches an action's trigger, that action is added to
     30 the tail of a to-be-executed queue (unless it is already on the
     31 queue).
     32 
     33 Each action in the queue is dequeued in sequence and each command in
     34 that action is executed in sequence.  Init handles other activities
     35 (device creation/destruction, property setting, process restarting)
     36 "between" the execution of the commands in activities.
     37 
     38 Actions take the form of:
     39 
     40 on <trigger>
     41    <command>
     42    <command>
     43    <command>
     44 
     45 
     46 Services
     47 --------
     48 Services are programs which init launches and (optionally) restarts
     49 when they exit.  Services take the form of:
     50 
     51 service <name> <pathname> [ <argument> ]*
     52    <option>
     53    <option>
     54    ...
     55 
     56 
     57 Options
     58 -------
     59 Options are modifiers to services.  They affect how and when init
     60 runs the service.
     61 
     62 critical
     63    This is a device-critical service. If it exits more than four times in
     64    four minutes, the device will reboot into recovery mode.
     65 
     66 disabled
     67    This service will not automatically start with its class.
     68    It must be explicitly started by name.
     69 
     70 setenv <name> <value>
     71    Set the environment variable <name> to <value> in the launched process.
     72 
     73 socket <name> <type> <perm> [ <user> [ <group> ] ]
     74    Create a unix domain socket named /dev/socket/<name> and pass
     75    its fd to the launched process.  <type> must be "dgram", "stream" or "seqpacket".
     76    User and group default to 0.
     77 
     78 user <username>
     79    Change to username before exec'ing this service.
     80    Currently defaults to root.  (??? probably should default to nobody)
     81    Currently, if your process requires linux capabilities then you cannot use
     82    this command. You must instead request the capabilities in-process while
     83    still root, and then drop to your desired uid.
     84 
     85 group <groupname> [ <groupname> ]*
     86    Change to groupname before exec'ing this service.  Additional
     87    groupnames beyond the (required) first one are used to set the
     88    supplemental groups of the process (via setgroups()).
     89    Currently defaults to root.  (??? probably should default to nobody)
     90 
     91 oneshot
     92    Do not restart the service when it exits.
     93 
     94 class <name>
     95    Specify a class name for the service.  All services in a
     96    named class may be started or stopped together.  A service
     97    is in the class "default" if one is not specified via the
     98    class option.
     99 
    100 onrestart
    101     Execute a Command (see below) when service restarts.
    102 
    103 Triggers
    104 --------
    105    Triggers are strings which can be used to match certain kinds
    106    of events and used to cause an action to occur.
    107 
    108 boot
    109    This is the first trigger that will occur when init starts
    110    (after /init.conf is loaded)
    111 
    112 <name>=<value>
    113    Triggers of this form occur when the property <name> is set
    114    to the specific value <value>.
    115 
    116 device-added-<path>
    117 device-removed-<path>
    118    Triggers of these forms occur when a device node is added
    119    or removed.
    120 
    121 service-exited-<name>
    122    Triggers of this form occur when the specified service exits.
    123 
    124 
    125 Commands
    126 --------
    127 
    128 exec <path> [ <argument> ]*
    129    Fork and execute a program (<path>).  This will block until
    130    the program completes execution.  It is best to avoid exec
    131    as unlike the builtin commands, it runs the risk of getting
    132    init "stuck". (??? maybe there should be a timeout?)
    133 
    134 export <name> <value>
    135    Set the environment variable <name> equal to <value> in the
    136    global environment (which will be inherited by all processes
    137    started after this command is executed)
    138 
    139 ifup <interface>
    140    Bring the network interface <interface> online.
    141 
    142 import <filename>
    143    Parse an init config file, extending the current configuration.
    144 
    145 hostname <name>
    146    Set the host name.
    147 
    148 chdir <directory>
    149    Change working directory.
    150 
    151 chmod <octal-mode> <path>
    152    Change file access permissions.
    153 
    154 chown <owner> <group> <path>
    155    Change file owner and group.
    156 
    157 chroot <directory>
    158   Change process root directory.
    159 
    160 class_start <serviceclass>
    161    Start all services of the specified class if they are
    162    not already running.
    163 
    164 class_stop <serviceclass>
    165    Stop all services of the specified class if they are
    166    currently running.
    167 
    168 domainname <name>
    169    Set the domain name.
    170 
    171 insmod <path>
    172    Install the module at <path>
    173 
    174 mkdir <path> [mode] [owner] [group]
    175    Create a directory at <path>, optionally with the given mode, owner, and
    176    group. If not provided, the directory is created with permissions 755 and
    177    owned by the root user and root group.
    178 
    179 mount <type> <device> <dir> [ <mountoption> ]*
    180    Attempt to mount the named device at the directory <dir>
    181    <device> may be of the form mtd@name to specify a mtd block
    182    device by name.
    183    <mountoption>s include "ro", "rw", "remount", "noatime", ...
    184 
    185 setkey
    186    TBD
    187 
    188 setprop <name> <value>
    189    Set system property <name> to <value>.
    190 
    191 setrlimit <resource> <cur> <max>
    192    Set the rlimit for a resource.
    193 
    194 start <service>
    195    Start a service running if it is not already running.
    196 
    197 stop <service>
    198    Stop a service from running if it is currently running.
    199 
    200 symlink <target> <path>
    201    Create a symbolic link at <path> with the value <target>
    202 
    203 sysclktz <mins_west_of_gmt>
    204    Set the system clock base (0 if system clock ticks in GMT)
    205 
    206 trigger <event>
    207    Trigger an event.  Used to queue an action from another
    208    action.
    209 
    210 write <path> <string> [ <string> ]*
    211    Open the file at <path> and write one or more strings
    212    to it with write(2)
    213 
    214 
    215 Properties
    216 ----------
    217 Init updates some system properties to provide some insight into
    218 what it's doing:
    219 
    220 init.action 
    221    Equal to the name of the action currently being executed or "" if none
    222 
    223 init.command
    224    Equal to the command being executed or "" if none.
    225 
    226 init.svc.<name>
    227    State of a named service ("stopped", "running", "restarting")
    228 
    229 
    230 Example init.conf
    231 -----------------
    232 
    233 # not complete -- just providing some examples of usage
    234 #
    235 on boot
    236    export PATH /sbin:/system/sbin:/system/bin
    237    export LD_LIBRARY_PATH /system/lib
    238 
    239    mkdir /dev
    240    mkdir /proc
    241    mkdir /sys
    242 
    243    mount tmpfs tmpfs /dev
    244    mkdir /dev/pts
    245    mkdir /dev/socket
    246    mount devpts devpts /dev/pts
    247    mount proc proc /proc
    248    mount sysfs sysfs /sys
    249 
    250    write /proc/cpu/alignment 4
    251 
    252    ifup lo
    253 
    254    hostname localhost
    255    domainname localhost
    256 
    257    mount yaffs2 mtd@system /system
    258    mount yaffs2 mtd@userdata /data
    259 
    260    import /system/etc/init.conf
    261 
    262    class_start default
    263 
    264 service adbd /sbin/adbd
    265    user adb
    266    group adb
    267 
    268 service usbd /system/bin/usbd -r
    269    user usbd
    270    group usbd
    271    socket usbd 666
    272 
    273 service zygote /system/bin/app_process -Xzygote /system/bin --zygote
    274    socket zygote 666
    275 
    276 service runtime /system/bin/runtime
    277    user system
    278    group system
    279 
    280 on device-added-/dev/compass
    281    start akmd
    282 
    283 on device-removed-/dev/compass
    284    stop akmd
    285 
    286 service akmd /sbin/akmd
    287    disabled
    288    user akmd
    289    group akmd
    290 
    291 Debugging notes
    292 ---------------
    293 By default, programs executed by init will drop stdout and stderr into
    294 /dev/null. To help with debugging, you can execute your program via the
    295 Andoird program logwrapper. This will redirect stdout/stderr into the
    296 Android logging system (accessed via logcat).
    297 
    298 For example
    299 service akmd /system/bin/logwrapper /sbin/akmd
    300