1Android Init Language 2--------------------- 3 4The Android Init Language consists of five broad classes of statements: 5Actions, Commands, Services, Options, and Imports. 6 7All of these are line-oriented, consisting of tokens separated by 8whitespace. The c-style backslash escapes may be used to insert 9whitespace into a token. Double quotes may also be used to prevent 10whitespace from breaking text into multiple tokens. The backslash, 11when it is the last character on a line, may be used for line-folding. 12 13Lines which start with a # (leading whitespace allowed) are comments. 14 15Actions and Services implicitly declare a new section. All commands 16or options belong to the section most recently declared. Commands 17or options before the first section are ignored. 18 19Actions and Services have unique names. If a second Action is defined 20with the same name as an existing one, its commands are appended to 21the commands of the existing action. If a second Service is defined 22with the same name as an existing one, it is ignored and an error 23message is logged. 24 25 26Init .rc Files 27-------------- 28The init language is used in plain text files that take the .rc file 29extension. There are typically multiple of these in multiple 30locations on the system, described below. 31 32/init.rc is the primary .rc file and is loaded by the init executable 33at the beginning of its execution. It is responsible for the initial 34set up of the system. It imports /init.${ro.hardware}.rc which is the 35primary vendor supplied .rc file. 36 37During the mount\_all command, the init executable loads all of the 38files contained within the /{system,vendor,odm}/etc/init/ directories. 39These directories are intended for all Actions and Services used after 40file system mounting. 41 42One may specify paths in the mount\_all command line to have it import 43.rc files at the specified paths instead of the default ones listed above. 44This is primarily for supporting factory mode and other non-standard boot 45modes. The three default paths should be used for the normal boot process. 46 47The intention of these directories is: 48 49 1. /system/etc/init/ is for core system items such as 50 SurfaceFlinger, MediaService, and logcatd. 51 2. /vendor/etc/init/ is for SoC vendor items such as actions or 52 daemons needed for core SoC functionality. 53 3. /odm/etc/init/ is for device manufacturer items such as 54 actions or daemons needed for motion sensor or other peripheral 55 functionality. 56 57All services whose binaries reside on the system, vendor, or odm 58partitions should have their service entries placed into a 59corresponding init .rc file, located in the /etc/init/ 60directory of the partition where they reside. There is a build 61system macro, LOCAL\_INIT\_RC, that handles this for developers. Each 62init .rc file should additionally contain any actions associated with 63its service. 64 65An example is the logcatd.rc and Android.mk files located in the 66system/core/logcat directory. The LOCAL\_INIT\_RC macro in the 67Android.mk file places logcatd.rc in /system/etc/init/ during the 68build process. Init loads logcatd.rc during the mount\_all command and 69allows the service to be run and the action to be queued when 70appropriate. 71 72This break up of init .rc files according to their daemon is preferred 73to the previously used monolithic init .rc files. This approach 74ensures that the only service entries that init reads and the only 75actions that init performs correspond to services whose binaries are in 76fact present on the file system, which was not the case with the 77monolithic init .rc files. This additionally will aid in merge 78conflict resolution when multiple services are added to the system, as 79each one will go into a separate file. 80 81There are two options "early" and "late" in mount\_all command 82which can be set after optional paths. With "--early" set, the 83init executable will skip mounting entries with "latemount" flag 84and triggering fs encryption state event. With "--late" set, 85init executable will only mount entries with "latemount" flag but skip 86importing rc files. By default, no option is set, and mount\_all will 87process all entries in the given fstab. 88 89Actions 90------- 91Actions are named sequences of commands. Actions have a trigger which 92is used to determine when the action should occur. When an event 93occurs which matches an action's trigger, that action is added to 94the tail of a to-be-executed queue (unless it is already on the 95queue). 96 97Each action in the queue is dequeued in sequence and each command in 98that action is executed in sequence. Init handles other activities 99(device creation/destruction, property setting, process restarting) 100"between" the execution of the commands in activities. 101 102Actions take the form of: 103 104 on <trigger> [&& <trigger>]* 105 <command> 106 <command> 107 <command> 108 109 110Services 111-------- 112Services are programs which init launches and (optionally) restarts 113when they exit. Services take the form of: 114 115 service <name> <pathname> [ <argument> ]* 116 <option> 117 <option> 118 ... 119 120 121Options 122------- 123Options are modifiers to services. They affect how and when init 124runs the service. 125 126`console [<console>]` 127> This service needs a console. The optional second parameter chooses a 128 specific console instead of the default. The default "/dev/console" can 129 be changed by setting the "androidboot.console" kernel parameter. In 130 all cases the leading "/dev/" should be omitted, so "/dev/tty0" would be 131 specified as just "console tty0". 132 133`critical` 134> This is a device-critical service. If it exits more than four times in 135 four minutes, the device will reboot into recovery mode. 136 137`disabled` 138> This service will not automatically start with its class. 139 It must be explicitly started by name. 140 141`setenv <name> <value>` 142> Set the environment variable _name_ to _value_ in the launched process. 143 144`socket <name> <type> <perm> [ <user> [ <group> [ <seclabel> ] ] ]` 145> Create a unix domain socket named /dev/socket/_name_ and pass its fd to the 146 launched process. _type_ must be "dgram", "stream" or "seqpacket". User and 147 group default to 0. 'seclabel' is the SELinux security context for the 148 socket. It defaults to the service security context, as specified by 149 seclabel or computed based on the service executable file security context. 150 For native executables see libcutils android\_get\_control\_socket(). 151 152`file <path> <type>` 153> Open a file path and pass its fd to the launched process. _type_ must be 154 "r", "w" or "rw". For native executables see libcutils 155 android\_get\_control\_file(). 156 157`user <username>` 158> Change to 'username' before exec'ing this service. 159 Currently defaults to root. (??? probably should default to nobody) 160 As of Android M, processes should use this option even if they 161 require Linux capabilities. Previously, to acquire Linux 162 capabilities, a process would need to run as root, request the 163 capabilities, then drop to its desired uid. There is a new 164 mechanism through fs\_config that allows device manufacturers to add 165 Linux capabilities to specific binaries on a file system that should 166 be used instead. This mechanism is described on 167 <http://source.android.com/devices/tech/config/filesystem.html>. When 168 using this new mechanism, processes can use the user option to 169 select their desired uid without ever running as root. 170 As of Android O, processes can also request capabilities directly in their .rc 171 files. See the "capabilities" option below. 172 173`group <groupname> [ <groupname>\* ]` 174> Change to 'groupname' before exec'ing this service. Additional 175 groupnames beyond the (required) first one are used to set the 176 supplemental groups of the process (via setgroups()). 177 Currently defaults to root. (??? probably should default to nobody) 178 179`capabilities <capability> [ <capability>\* ]` 180> Set capabilities when exec'ing this service. 'capability' should be a Linux 181 capability without the "CAP\_" prefix, like "NET\_ADMIN" or "SETPCAP". See 182 http://man7.org/linux/man-pages/man7/capabilities.7.html for a list of Linux 183 capabilities. 184 185`seclabel <seclabel>` 186> Change to 'seclabel' before exec'ing this service. 187 Primarily for use by services run from the rootfs, e.g. ueventd, adbd. 188 Services on the system partition can instead use policy-defined transitions 189 based on their file security context. 190 If not specified and no transition is defined in policy, defaults to the init context. 191 192`oneshot` 193> Do not restart the service when it exits. 194 195`class <name> [ <name>\* ]` 196> Specify class names for the service. All services in a 197 named class may be started or stopped together. A service 198 is in the class "default" if one is not specified via the 199 class option. Additional classnames beyond the (required) first 200 one are used to group services. 201`animation class` 202> 'animation' class should include all services necessary for both 203 boot animation and shutdown animation. As these services can be 204 launched very early during bootup and can run until the last stage 205 of shutdown, access to /data partition is not guaranteed. These 206 services can check files under /data but it should not keep files opened 207 and should work when /data is not available. 208 209`onrestart` 210> Execute a Command (see below) when service restarts. 211 212`writepid <file> [ <file>\* ]` 213> Write the child's pid to the given files when it forks. Meant for 214 cgroup/cpuset usage. If no files under /dev/cpuset/ are specified, but the 215 system property 'ro.cpuset.default' is set to a non-empty cpuset name (e.g. 216 '/foreground'), then the pid is written to file /dev/cpuset/_cpuset\_name_/tasks. 217 218`priority <priority>` 219> Scheduling priority of the service process. This value has to be in range 220 -20 to 19. Default priority is 0. Priority is set via setpriority(). 221 222`namespace <pid|mnt>` 223> Enter a new PID or mount namespace when forking the service. 224 225`oom_score_adjust <value>` 226> Sets the child's /proc/self/oom\_score\_adj to the specified value, 227 which must range from -1000 to 1000. 228 229 230Triggers 231-------- 232Triggers are strings which can be used to match certain kinds of 233events and used to cause an action to occur. 234 235Triggers are subdivided into event triggers and property triggers. 236 237Event triggers are strings triggered by the 'trigger' command or by 238the QueueEventTrigger() function within the init executable. These 239take the form of a simple string such as 'boot' or 'late-init'. 240 241Property triggers are strings triggered when a named property changes 242value to a given new value or when a named property changes value to 243any new value. These take the form of 'property:<name>=<value>' and 244'property:<name>=\*' respectively. Property triggers are additionally 245evaluated and triggered accordingly during the initial boot phase of 246init. 247 248An Action can have multiple property triggers but may only have one 249event trigger. 250 251For example: 252`on boot && property:a=b` defines an action that is only executed when 253the 'boot' event trigger happens and the property a equals b. 254 255`on property:a=b && property:c=d` defines an action that is executed 256at three times: 257 258 1. During initial boot if property a=b and property c=d. 259 2. Any time that property a transitions to value b, while property c already equals d. 260 3. Any time that property c transitions to value d, while property a already equals b. 261 262 263Commands 264-------- 265 266`bootchart [start|stop]` 267> Start/stop bootcharting. These are present in the default init.rc files, 268 but bootcharting is only active if the file /data/bootchart/enabled exists; 269 otherwise bootchart start/stop are no-ops. 270 271`chmod <octal-mode> <path>` 272> Change file access permissions. 273 274`chown <owner> <group> <path>` 275> Change file owner and group. 276 277`class_start <serviceclass>` 278> Start all services of the specified class if they are 279 not already running. 280 281`class_stop <serviceclass>` 282> Stop and disable all services of the specified class if they are 283 currently running. 284 285`class_reset <serviceclass>` 286> Stop all services of the specified class if they are 287 currently running, without disabling them. They can be restarted 288 later using `class_start`. 289 290`class_restart <serviceclass>` 291> Restarts all services of the specified class. 292 293`copy <src> <dst>` 294> Copies a file. Similar to write, but useful for binary/large 295 amounts of data. 296 Regarding to the src file, copying from symbolic link file and world-writable 297 or group-writable files are not allowed. 298 Regarding to the dst file, the default mode created is 0600 if it does not 299 exist. And it will be truncated if dst file is a normal regular file and 300 already exists. 301 302`domainname <name>` 303> Set the domain name. 304 305`enable <servicename>` 306> Turns a disabled service into an enabled one as if the service did not 307 specify disabled. 308 If the service is supposed to be running, it will be started now. 309 Typically used when the bootloader sets a variable that indicates a specific 310 service should be started when needed. E.g. 311 312 on property:ro.boot.myfancyhardware=1 313 enable my_fancy_service_for_my_fancy_hardware 314 315`exec [ <seclabel> [ <user> [ <group>\* ] ] ] -- <command> [ <argument>\* ]` 316> Fork and execute command with the given arguments. The command starts 317 after "--" so that an optional security context, user, and supplementary 318 groups can be provided. No other commands will be run until this one 319 finishes. _seclabel_ can be a - to denote default. Properties are expanded 320 within _argument_. 321 Init halts executing commands until the forked process exits. 322 323`exec_start <service>` 324> Start service a given service and halt processing of additional init commands 325 until it returns. It functions similarly to the `exec` command, but uses an 326 existing service definition instead of providing them as arguments. 327 328`export <name> <value>` 329> Set the environment variable _name_ equal to _value_ in the 330 global environment (which will be inherited by all processes 331 started after this command is executed) 332 333`hostname <name>` 334> Set the host name. 335 336`ifup <interface>` 337> Bring the network interface _interface_ online. 338 339`insmod [-f] <path> [<options>]` 340> Install the module at _path_ with the specified options. 341 -f: force installation of the module even if the version of the running kernel 342 and the version of the kernel for which the module was compiled do not match. 343 344`load_all_props` 345> Loads properties from /system, /vendor, et cetera. 346 This is included in the default init.rc. 347 348`load_persist_props` 349> Loads persistent properties when /data has been decrypted. 350 This is included in the default init.rc. 351 352`loglevel <level>` 353> Sets the kernel log level to level. Properties are expanded within _level_. 354 355`mkdir <path> [mode] [owner] [group]` 356> Create a directory at _path_, optionally with the given mode, owner, and 357 group. If not provided, the directory is created with permissions 755 and 358 owned by the root user and root group. If provided, the mode, owner and group 359 will be updated if the directory exists already. 360 361`mount_all <fstab> [ <path> ]\* [--<option>]` 362> Calls fs\_mgr\_mount\_all on the given fs\_mgr-format fstab and imports .rc files 363 at the specified paths (e.g., on the partitions just mounted) with optional 364 options "early" and "late". 365 Refer to the section of "Init .rc Files" for detail. 366 367`mount <type> <device> <dir> [ <flag>\* ] [<options>]` 368> Attempt to mount the named device at the directory _dir_ 369 _flag_s include "ro", "rw", "remount", "noatime", ... 370 _options_ include "barrier=1", "noauto\_da\_alloc", "discard", ... as 371 a comma separated string, eg: barrier=1,noauto\_da\_alloc 372 373`restart <service>` 374> Stops and restarts a running service, does nothing if the service is currently 375 restarting, otherwise, it just starts the service. 376 377`restorecon <path> [ <path>\* ]` 378> Restore the file named by _path_ to the security context specified 379 in the file\_contexts configuration. 380 Not required for directories created by the init.rc as these are 381 automatically labeled correctly by init. 382 383`restorecon_recursive <path> [ <path>\* ]` 384> Recursively restore the directory tree named by _path_ to the 385 security contexts specified in the file\_contexts configuration. 386 387`rm <path>` 388> Calls unlink(2) on the given path. You might want to 389 use "exec -- rm ..." instead (provided the system partition is 390 already mounted). 391 392`rmdir <path>` 393> Calls rmdir(2) on the given path. 394 395`setprop <name> <value>` 396> Set system property _name_ to _value_. Properties are expanded 397 within _value_. 398 399`setrlimit <resource> <cur> <max>` 400> Set the rlimit for a resource. 401 402`start <service>` 403> Start a service running if it is not already running. 404 405`stop <service>` 406> Stop a service from running if it is currently running. 407 408`swapon_all <fstab>` 409> Calls fs\_mgr\_swapon\_all on the given fstab file. 410 411`symlink <target> <path>` 412> Create a symbolic link at _path_ with the value _target_ 413 414`sysclktz <mins_west_of_gmt>` 415> Set the system clock base (0 if system clock ticks in GMT) 416 417`trigger <event>` 418> Trigger an event. Used to queue an action from another 419 action. 420 421`umount <path>` 422> Unmount the filesystem mounted at that path. 423 424`verity_load_state` 425> Internal implementation detail used to load dm-verity state. 426 427`verity_update_state <mount-point>` 428> Internal implementation detail used to update dm-verity state and 429 set the partition._mount-point_.verified properties used by adb remount 430 because fs\_mgr can't set them directly itself. 431 432`wait <path> [ <timeout> ]` 433> Poll for the existence of the given file and return when found, 434 or the timeout has been reached. If timeout is not specified it 435 currently defaults to five seconds. 436 437`wait_for_prop <name> <value>` 438> Wait for system property _name_ to be _value_. Properties are expanded 439 within _value_. If property _name_ is already set to _value_, continue 440 immediately. 441 442`write <path> <content>` 443> Open the file at _path_ and write a string to it with write(2). 444 If the file does not exist, it will be created. If it does exist, 445 it will be truncated. Properties are expanded within _content_. 446 447 448Imports 449------- 450The import keyword is not a command, but rather its own section and is 451handled immediately after the .rc file that contains it has finished 452being parsed. It takes the below form: 453 454`import <path>` 455> Parse an init config file, extending the current configuration. 456 If _path_ is a directory, each file in the directory is parsed as 457 a config file. It is not recursive, nested directories will 458 not be parsed. 459 460There are only two times where the init executable imports .rc files: 461 462 1. When it imports /init.rc during initial boot 463 2. When it imports /{system,vendor,odm}/etc/init/ or .rc files at specified 464 paths during mount_all 465 466 467Properties 468---------- 469Init provides information about the services that it is responsible 470for via the below properties. 471 472`init.svc.<name>` 473> State of a named service ("stopped", "stopping", "running", "restarting") 474 475 476Boot timing 477----------- 478Init records some boot timing information in system properties. 479 480`ro.boottime.init` 481> Time after boot in ns (via the CLOCK\_BOOTTIME clock) at which the first 482 stage of init started. 483 484`ro.boottime.init.selinux` 485> How long it took the first stage to initialize SELinux. 486 487`ro.boottime.init.cold_boot_wait` 488> How long init waited for ueventd's coldboot phase to end. 489 490`ro.boottime.<service-name>` 491> Time after boot in ns (via the CLOCK\_BOOTTIME clock) that the service was 492 first started. 493 494 495Bootcharting 496------------ 497This version of init contains code to perform "bootcharting": generating log 498files that can be later processed by the tools provided by <http://www.bootchart.org/>. 499 500On the emulator, use the -bootchart _timeout_ option to boot with bootcharting 501activated for _timeout_ seconds. 502 503On a device: 504 505 adb shell 'touch /data/bootchart/enabled' 506 507Don't forget to delete this file when you're done collecting data! 508 509The log files are written to /data/bootchart/. A script is provided to 510retrieve them and create a bootchart.tgz file that can be used with the 511bootchart command-line utility: 512 513 sudo apt-get install pybootchartgui 514 # grab-bootchart.sh uses $ANDROID_SERIAL. 515 $ANDROID_BUILD_TOP/system/core/init/grab-bootchart.sh 516 517One thing to watch for is that the bootchart will show init as if it started 518running at 0s. You'll have to look at dmesg to work out when the kernel 519actually started init. 520 521 522Comparing two bootcharts 523------------------------ 524A handy script named compare-bootcharts.py can be used to compare the 525start/end time of selected processes. The aforementioned grab-bootchart.sh 526will leave a bootchart tarball named bootchart.tgz at /tmp/android-bootchart. 527If two such barballs are preserved on the host machine under different 528directories, the script can list the timestamps differences. For example: 529 530Usage: system/core/init/compare-bootcharts.py _base-bootchart-dir_ _exp-bootchart-dir_ 531 532 process: baseline experiment (delta) - Unit is ms (a jiffy is 10 ms on the system) 533 ------------------------------------ 534 /init: 50 40 (-10) 535 /system/bin/surfaceflinger: 4320 4470 (+150) 536 /system/bin/bootanimation: 6980 6990 (+10) 537 zygote64: 10410 10640 (+230) 538 zygote: 10410 10640 (+230) 539 system_server: 15350 15150 (-200) 540 bootanimation ends at: 33790 31230 (-2560) 541 542 543Systrace 544-------- 545Systrace (<http://developer.android.com/tools/help/systrace.html>) can be 546used for obtaining performance analysis reports during boot 547time on userdebug or eng builds. 548 549Here is an example of trace events of "wm" and "am" categories: 550 551 $ANDROID_BUILD_TOP/external/chromium-trace/systrace.py \ 552 wm am --boot 553 554This command will cause the device to reboot. After the device is rebooted and 555the boot sequence has finished, the trace report is obtained from the device 556and written as trace.html on the host by hitting Ctrl+C. 557 558Limitation: recording trace events is started after persistent properties are loaded, so 559the trace events that are emitted before that are not recorded. Several 560services such as vold, surfaceflinger, and servicemanager are affected by this 561limitation since they are started before persistent properties are loaded. 562Zygote initialization and the processes that are forked from the zygote are not 563affected. 564 565 566Debugging init 567-------------- 568By default, programs executed by init will drop stdout and stderr into 569/dev/null. To help with debugging, you can execute your program via the 570Android program logwrapper. This will redirect stdout/stderr into the 571Android logging system (accessed via logcat). 572 573For example 574service akmd /system/bin/logwrapper /sbin/akmd 575 576For quicker turnaround when working on init itself, use: 577 578 mm -j && 579 m ramdisk-nodeps && 580 m bootimage-nodeps && 581 adb reboot bootloader && 582 fastboot boot $ANDROID_PRODUCT_OUT/boot.img 583 584Alternatively, use the emulator: 585 586 emulator -partition-size 1024 \ 587 -verbose -show-kernel -no-window 588