1 Android Init Language 2 --------------------- 3 4 The Android Init Language consists of five broad classes of statements: 5 Actions, Commands, Services, Options, and Imports. 6 7 All of these are line-oriented, consisting of tokens separated by 8 whitespace. The c-style backslash escapes may be used to insert 9 whitespace into a token. Double quotes may also be used to prevent 10 whitespace from breaking text into multiple tokens. The backslash, 11 when it is the last character on a line, may be used for line-folding. 12 13 Lines which start with a # (leading whitespace allowed) are comments. 14 15 Actions and Services implicitly declare a new section. All commands 16 or options belong to the section most recently declared. Commands 17 or options before the first section are ignored. 18 19 Actions and Services have unique names. If a second Action is defined 20 with the same name as an existing one, its commands are appended to 21 the commands of the existing action. If a second Service is defined 22 with the same name as an existing one, it is ignored and an error 23 message is logged. 24 25 26 Init .rc Files 27 -------------- 28 The init language is used in plain text files that take the .rc file 29 extension. There are typically multiple of these in multiple 30 locations on the system, described below. 31 32 /init.rc is the primary .rc file and is loaded by the init executable 33 at the beginning of its execution. It is responsible for the initial 34 set up of the system. It imports /init.${ro.hardware}.rc which is the 35 primary vendor supplied .rc file. 36 37 During the mount\_all command, the init executable loads all of the 38 files contained within the /{system,vendor,odm}/etc/init/ directories. 39 These directories are intended for all Actions and Services used after 40 file system mounting. 41 42 One 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. 44 This is primarily for supporting factory mode and other non-standard boot 45 modes. The three default paths should be used for the normal boot process. 46 47 The 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 57 All services whose binaries reside on the system, vendor, or odm 58 partitions should have their service entries placed into a 59 corresponding init .rc file, located in the /etc/init/ 60 directory of the partition where they reside. There is a build 61 system macro, LOCAL\_INIT\_RC, that handles this for developers. Each 62 init .rc file should additionally contain any actions associated with 63 its service. 64 65 An example is the logcatd.rc and Android.mk files located in the 66 system/core/logcat directory. The LOCAL\_INIT\_RC macro in the 67 Android.mk file places logcatd.rc in /system/etc/init/ during the 68 build process. Init loads logcatd.rc during the mount\_all command and 69 allows the service to be run and the action to be queued when 70 appropriate. 71 72 This break up of init .rc files according to their daemon is preferred 73 to the previously used monolithic init .rc files. This approach 74 ensures that the only service entries that init reads and the only 75 actions that init performs correspond to services whose binaries are in 76 fact present on the file system, which was not the case with the 77 monolithic init .rc files. This additionally will aid in merge 78 conflict resolution when multiple services are added to the system, as 79 each one will go into a separate file. 80 81 There are two options "early" and "late" in mount\_all command 82 which can be set after optional paths. With "--early" set, the 83 init executable will skip mounting entries with "latemount" flag 84 and triggering fs encryption state event. With "--late" set, 85 init executable will only mount entries with "latemount" flag but skip 86 importing rc files. By default, no option is set, and mount\_all will 87 process all entries in the given fstab. 88 89 Actions 90 ------- 91 Actions are named sequences of commands. Actions have a trigger which 92 is used to determine when the action should occur. When an event 93 occurs which matches an action's trigger, that action is added to 94 the tail of a to-be-executed queue (unless it is already on the 95 queue). 96 97 Each action in the queue is dequeued in sequence and each command in 98 that 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 102 Actions take the form of: 103 104 on <trigger> [&& <trigger>]* 105 <command> 106 <command> 107 <command> 108 109 110 Services 111 -------- 112 Services are programs which init launches and (optionally) restarts 113 when they exit. Services take the form of: 114 115 service <name> <pathname> [ <argument> ]* 116 <option> 117 <option> 118 ... 119 120 121 Options 122 ------- 123 Options are modifiers to services. They affect how and when init 124 runs 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 230 Triggers 231 -------- 232 Triggers are strings which can be used to match certain kinds of 233 events and used to cause an action to occur. 234 235 Triggers are subdivided into event triggers and property triggers. 236 237 Event triggers are strings triggered by the 'trigger' command or by 238 the QueueEventTrigger() function within the init executable. These 239 take the form of a simple string such as 'boot' or 'late-init'. 240 241 Property triggers are strings triggered when a named property changes 242 value to a given new value or when a named property changes value to 243 any new value. These take the form of 'property:<name>=<value>' and 244 'property:<name>=\*' respectively. Property triggers are additionally 245 evaluated and triggered accordingly during the initial boot phase of 246 init. 247 248 An Action can have multiple property triggers but may only have one 249 event trigger. 250 251 For example: 252 `on boot && property:a=b` defines an action that is only executed when 253 the '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 256 at 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 263 Commands 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 448 Imports 449 ------- 450 The import keyword is not a command, but rather its own section and is 451 handled immediately after the .rc file that contains it has finished 452 being 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 460 There 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 467 Properties 468 ---------- 469 Init provides information about the services that it is responsible 470 for via the below properties. 471 472 `init.svc.<name>` 473 > State of a named service ("stopped", "stopping", "running", "restarting") 474 475 476 Boot timing 477 ----------- 478 Init 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 495 Bootcharting 496 ------------ 497 This version of init contains code to perform "bootcharting": generating log 498 files that can be later processed by the tools provided by <http://www.bootchart.org/>. 499 500 On the emulator, use the -bootchart _timeout_ option to boot with bootcharting 501 activated for _timeout_ seconds. 502 503 On a device: 504 505 adb shell 'touch /data/bootchart/enabled' 506 507 Don't forget to delete this file when you're done collecting data! 508 509 The log files are written to /data/bootchart/. A script is provided to 510 retrieve them and create a bootchart.tgz file that can be used with the 511 bootchart 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 517 One thing to watch for is that the bootchart will show init as if it started 518 running at 0s. You'll have to look at dmesg to work out when the kernel 519 actually started init. 520 521 522 Comparing two bootcharts 523 ------------------------ 524 A handy script named compare-bootcharts.py can be used to compare the 525 start/end time of selected processes. The aforementioned grab-bootchart.sh 526 will leave a bootchart tarball named bootchart.tgz at /tmp/android-bootchart. 527 If two such barballs are preserved on the host machine under different 528 directories, the script can list the timestamps differences. For example: 529 530 Usage: 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 543 Systrace 544 -------- 545 Systrace (<http://developer.android.com/tools/help/systrace.html>) can be 546 used for obtaining performance analysis reports during boot 547 time on userdebug or eng builds. 548 549 Here 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 554 This command will cause the device to reboot. After the device is rebooted and 555 the boot sequence has finished, the trace report is obtained from the device 556 and written as trace.html on the host by hitting Ctrl+C. 557 558 Limitation: recording trace events is started after persistent properties are loaded, so 559 the trace events that are emitted before that are not recorded. Several 560 services such as vold, surfaceflinger, and servicemanager are affected by this 561 limitation since they are started before persistent properties are loaded. 562 Zygote initialization and the processes that are forked from the zygote are not 563 affected. 564 565 566 Debugging init 567 -------------- 568 By 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 570 Android program logwrapper. This will redirect stdout/stderr into the 571 Android logging system (accessed via logcat). 572 573 For example 574 service akmd /system/bin/logwrapper /sbin/akmd 575 576 For 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 584 Alternatively, use the emulator: 585 586 emulator -partition-size 1024 \ 587 -verbose -show-kernel -no-window 588