1 Android Init Language 2 --------------------- 3 4 The Android Init Language consists of five broad classes of statements, 5 which are 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 plaintext files that take the .rc file 29 extension. These 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 as follows 48 1) /system/etc/init/ is for core system items such as 49 SurfaceFlinger, MediaService, and logcatd. 50 2) /vendor/etc/init/ is for SoC vendor items such as actions or 51 daemons needed for core SoC functionality. 52 3) /odm/etc/init/ is for device manufacturer items such as 53 actions or daemons needed for motion sensor or other peripheral 54 functionality. 55 56 All services whose binaries reside on the system, vendor, or odm 57 partitions should have their service entries placed into a 58 corresponding init .rc file, located in the /etc/init/ 59 directory of the partition where they reside. There is a build 60 system macro, LOCAL_INIT_RC, that handles this for developers. Each 61 init .rc file should additionally contain any actions associated with 62 its service. 63 64 An example is the logcatd.rc and Android.mk files located in the 65 system/core/logcat directory. The LOCAL_INIT_RC macro in the 66 Android.mk file places logcatd.rc in /system/etc/init/ during the 67 build process. Init loads logcatd.rc during the mount_all command and 68 allows the service to be run and the action to be queued when 69 appropriate. 70 71 This break up of init .rc files according to their daemon is preferred 72 to the previously used monolithic init .rc files. This approach 73 ensures that the only service entries that init reads and the only 74 actions that init performs correspond to services whose binaries are in 75 fact present on the file system, which was not the case with the 76 monolithic init .rc files. This additionally will aid in merge 77 conflict resolution when multiple services are added to the system, as 78 each one will go into a separate file. 79 80 There are two options "early" and "late" in mount_all command 81 which can be set after optional paths. With "--early" set, the 82 init executable will skip mounting entries with "latemount" flag 83 and triggering fs encryption state event. With "--late" set, 84 init executable will only mount entries with "latemount" flag but skip 85 importing rc files. By default, no option is set, and mount_all will 86 mount_all will process all entries in the given fstab. 87 88 Actions 89 ------- 90 Actions are named sequences of commands. Actions have a trigger which 91 is used to determine when the action should occur. When an event 92 occurs which matches an action's trigger, that action is added to 93 the tail of a to-be-executed queue (unless it is already on the 94 queue). 95 96 Each action in the queue is dequeued in sequence and each command in 97 that action is executed in sequence. Init handles other activities 98 (device creation/destruction, property setting, process restarting) 99 "between" the execution of the commands in activities. 100 101 Actions take the form of: 102 103 on <trigger> [&& <trigger>]* 104 <command> 105 <command> 106 <command> 107 108 109 Services 110 -------- 111 Services are programs which init launches and (optionally) restarts 112 when they exit. Services take the form of: 113 114 service <name> <pathname> [ <argument> ]* 115 <option> 116 <option> 117 ... 118 119 120 Options 121 ------- 122 Options are modifiers to services. They affect how and when init 123 runs the service. 124 125 critical 126 This is a device-critical service. If it exits more than four times in 127 four minutes, the device will reboot into recovery mode. 128 129 disabled 130 This service will not automatically start with its class. 131 It must be explicitly started by name. 132 133 setenv <name> <value> 134 Set the environment variable <name> to <value> in the launched process. 135 136 socket <name> <type> <perm> [ <user> [ <group> [ <seclabel> ] ] ] 137 Create a unix domain socket named /dev/socket/<name> and pass 138 its fd to the launched process. <type> must be "dgram", "stream" or "seqpacket". 139 User and group default to 0. 140 'seclabel' is the SELinux security context for the socket. 141 It defaults to the service security context, as specified by seclabel or 142 computed based on the service executable file security context. 143 144 user <username> 145 Change to username before exec'ing this service. 146 Currently defaults to root. (??? probably should default to nobody) 147 As of Android M, processes should use this option even if they 148 require linux capabilities. Previously, to acquire linux 149 capabilities, a process would need to run as root, request the 150 capabilities, then drop to its desired uid. There is a new 151 mechanism through fs_config that allows device manufacturers to add 152 linux capabilities to specific binaries on a file system that should 153 be used instead. This mechanism is described on 154 http://source.android.com/devices/tech/config/filesystem.html. When 155 using this new mechanism, processes can use the user option to 156 select their desired uid without ever running as root. 157 158 group <groupname> [ <groupname> ]* 159 Change to groupname before exec'ing this service. Additional 160 groupnames beyond the (required) first one are used to set the 161 supplemental groups of the process (via setgroups()). 162 Currently defaults to root. (??? probably should default to nobody) 163 164 seclabel <seclabel> 165 Change to 'seclabel' before exec'ing this service. 166 Primarily for use by services run from the rootfs, e.g. ueventd, adbd. 167 Services on the system partition can instead use policy-defined transitions 168 based on their file security context. 169 If not specified and no transition is defined in policy, defaults to the init context. 170 171 oneshot 172 Do not restart the service when it exits. 173 174 class <name> 175 Specify a class name for the service. All services in a 176 named class may be started or stopped together. A service 177 is in the class "default" if one is not specified via the 178 class option. 179 180 onrestart 181 Execute a Command (see below) when service restarts. 182 183 writepid <file...> 184 Write the child's pid to the given files when it forks. Meant for 185 cgroup/cpuset usage. 186 187 188 Triggers 189 -------- 190 Triggers are strings which can be used to match certain kinds of 191 events and used to cause an action to occur. 192 193 Triggers are subdivided into event triggers and property triggers. 194 195 Event triggers are strings triggered by the 'trigger' command or by 196 the QueueEventTrigger() function within the init executable. These 197 take the form of a simple string such as 'boot' or 'late-init'. 198 199 Property triggers are strings triggered when a named property changes 200 value to a given new value or when a named property changes value to 201 any new value. These take the form of 'property:<name>=<value>' and 202 'property:<name>=*' respectively. Property triggers are additionally 203 evaluated and triggered accordingly during the initial boot phase of 204 init. 205 206 An Action can have multiple property triggers but may only have one 207 event trigger. 208 209 For example: 210 'on boot && property:a=b' defines an action that is only executed when 211 the 'boot' event trigger happens and the property a equals b. 212 213 'on property:a=b && property:c=d' defines an action that is executed 214 at three times, 215 1) During initial boot if property a=b and property c=d 216 2) Any time that property a transitions to value b, while property 217 c already equals d. 218 3) Any time that property c transitions to value d, while property 219 a already equals b. 220 221 222 Commands 223 -------- 224 225 bootchart_init 226 Start bootcharting if configured (see below). 227 This is included in the default init.rc. 228 229 chmod <octal-mode> <path> 230 Change file access permissions. 231 232 chown <owner> <group> <path> 233 Change file owner and group. 234 235 class_start <serviceclass> 236 Start all services of the specified class if they are 237 not already running. 238 239 class_stop <serviceclass> 240 Stop and disable all services of the specified class if they are 241 currently running. 242 243 class_reset <serviceclass> 244 Stop all services of the specified class if they are 245 currently running, without disabling them. They can be restarted 246 later using class_start. 247 248 copy <src> <dst> 249 Copies a file. Similar to write, but useful for binary/large 250 amounts of data. 251 252 domainname <name> 253 Set the domain name. 254 255 enable <servicename> 256 Turns a disabled service into an enabled one as if the service did not 257 specify disabled. 258 If the service is supposed to be running, it will be started now. 259 Typically used when the bootloader sets a variable that indicates a specific 260 service should be started when needed. E.g. 261 on property:ro.boot.myfancyhardware=1 262 enable my_fancy_service_for_my_fancy_hardware 263 264 exec [ <seclabel> [ <user> [ <group> ]* ] ] -- <command> [ <argument> ]* 265 Fork and execute command with the given arguments. The command starts 266 after "--" so that an optional security context, user, and supplementary 267 groups can be provided. No other commands will be run until this one 268 finishes. <seclabel> can be a - to denote default. 269 270 export <name> <value> 271 Set the environment variable <name> equal to <value> in the 272 global environment (which will be inherited by all processes 273 started after this command is executed) 274 275 hostname <name> 276 Set the host name. 277 278 ifup <interface> 279 Bring the network interface <interface> online. 280 281 insmod <path> 282 Install the module at <path> 283 284 load_all_props 285 Loads properties from /system, /vendor, et cetera. 286 This is included in the default init.rc. 287 288 load_persist_props 289 Loads persistent properties when /data has been decrypted. 290 This is included in the default init.rc. 291 292 loglevel <level> 293 Sets the kernel log level to level. Properties are expanded within <level>. 294 295 mkdir <path> [mode] [owner] [group] 296 Create a directory at <path>, optionally with the given mode, owner, and 297 group. If not provided, the directory is created with permissions 755 and 298 owned by the root user and root group. If provided, the mode, owner and group 299 will be updated if the directory exists already. 300 301 mount_all <fstab> [ <path> ]* [--<option>] 302 Calls fs_mgr_mount_all on the given fs_mgr-format fstab and imports .rc files 303 at the specified paths (e.g., on the partitions just mounted) with optional 304 options "early" and "late". 305 Refer to the section of "Init .rc Files" for detail. 306 307 mount <type> <device> <dir> [ <flag> ]* [<options>] 308 Attempt to mount the named device at the directory <dir> 309 <device> may be of the form mtd@name to specify a mtd block 310 device by name. 311 <flag>s include "ro", "rw", "remount", "noatime", ... 312 <options> include "barrier=1", "noauto_da_alloc", "discard", ... as 313 a comma separated string, eg: barrier=1,noauto_da_alloc 314 315 powerctl 316 Internal implementation detail used to respond to changes to the 317 "sys.powerctl" system property, used to implement rebooting. 318 319 restart <service> 320 Like stop, but doesn't disable the service. 321 322 restorecon <path> [ <path> ]* 323 Restore the file named by <path> to the security context specified 324 in the file_contexts configuration. 325 Not required for directories created by the init.rc as these are 326 automatically labeled correctly by init. 327 328 restorecon_recursive <path> [ <path> ]* 329 Recursively restore the directory tree named by <path> to the 330 security contexts specified in the file_contexts configuration. 331 332 rm <path> 333 Calls unlink(2) on the given path. You might want to 334 use "exec -- rm ..." instead (provided the system partition is 335 already mounted). 336 337 rmdir <path> 338 Calls rmdir(2) on the given path. 339 340 setprop <name> <value> 341 Set system property <name> to <value>. Properties are expanded 342 within <value>. 343 344 setrlimit <resource> <cur> <max> 345 Set the rlimit for a resource. 346 347 start <service> 348 Start a service running if it is not already running. 349 350 stop <service> 351 Stop a service from running if it is currently running. 352 353 swapon_all <fstab> 354 Calls fs_mgr_swapon_all on the given fstab file. 355 356 symlink <target> <path> 357 Create a symbolic link at <path> with the value <target> 358 359 sysclktz <mins_west_of_gmt> 360 Set the system clock base (0 if system clock ticks in GMT) 361 362 trigger <event> 363 Trigger an event. Used to queue an action from another 364 action. 365 366 umount <path> 367 Unmount the filesystem mounted at that path. 368 369 verity_load_state 370 Internal implementation detail used to load dm-verity state. 371 372 verity_update_state <mount_point> 373 Internal implementation detail used to update dm-verity state and 374 set the partition.<mount_point>.verified properties used by adb remount 375 because fs_mgr can't set them directly itself. 376 377 wait <path> [ <timeout> ] 378 Poll for the existence of the given file and return when found, 379 or the timeout has been reached. If timeout is not specified it 380 currently defaults to five seconds. 381 382 write <path> <content> 383 Open the file at <path> and write a string to it with write(2). 384 If the file does not exist, it will be created. If it does exist, 385 it will be truncated. Properties are expanded within <content>. 386 387 388 Imports 389 ------- 390 The import keyword is not a command, but rather its own section and is 391 handled immediately after the .rc file that contains it has finished 392 being parsed. It takes the below form: 393 394 import <path> 395 Parse an init config file, extending the current configuration. 396 If <path> is a directory, each file in the directory is parsed as 397 a config file. It is not recursive, nested directories will 398 not be parsed. 399 400 There are only two times where the init executable imports .rc files, 401 1) When it imports /init.rc during initial boot 402 2) When it imports /{system,vendor,odm}/etc/init/ or .rc files at specified 403 paths during mount_all 404 405 406 Properties 407 ---------- 408 Init provides information about the services that it is responsible 409 for via the below properties. 410 411 init.svc.<name> 412 State of a named service ("stopped", "stopping", "running", "restarting") 413 414 415 Bootcharting 416 ------------ 417 This version of init contains code to perform "bootcharting": generating log 418 files that can be later processed by the tools provided by www.bootchart.org. 419 420 On the emulator, use the -bootchart <timeout> option to boot with bootcharting 421 activated for <timeout> seconds. 422 423 On a device, create /data/bootchart/start with a command like the following: 424 425 adb shell 'echo $TIMEOUT > /data/bootchart/start' 426 427 Where the value of $TIMEOUT corresponds to the desired bootcharted period in 428 seconds. Bootcharting will stop after that many seconds have elapsed. 429 You can also stop the bootcharting at any moment by doing the following: 430 431 adb shell 'echo 1 > /data/bootchart/stop' 432 433 Note that /data/bootchart/stop is deleted automatically by init at the end of 434 the bootcharting. This is not the case with /data/bootchart/start, so don't 435 forget to delete it when you're done collecting data. 436 437 The log files are written to /data/bootchart/. A script is provided to 438 retrieve them and create a bootchart.tgz file that can be used with the 439 bootchart command-line utility: 440 441 sudo apt-get install pybootchartgui 442 # grab-bootchart.sh uses $ANDROID_SERIAL. 443 $ANDROID_BUILD_TOP/system/core/init/grab-bootchart.sh 444 445 One thing to watch for is that the bootchart will show init as if it started 446 running at 0s. You'll have to look at dmesg to work out when the kernel 447 actually started init. 448 449 450 Comparing two bootcharts 451 ------------------------ 452 A handy script named compare-bootcharts.py can be used to compare the 453 start/end time of selected processes. The aforementioned grab-bootchart.sh 454 will leave a bootchart tarball named bootchart.tgz at /tmp/android-bootchart. 455 If two such barballs are preserved on the host machine under different 456 directories, the script can list the timestamps differences. For example: 457 458 Usage: system/core/init/compare-bootcharts.py base_bootchart_dir 459 exp_bootchart_dir 460 461 process: baseline experiment (delta) 462 - Unit is ms (a jiffy is 10 ms on the system) 463 ------------------------------------ 464 /init: 50 40 (-10) 465 /system/bin/surfaceflinger: 4320 4470 (+150) 466 /system/bin/bootanimation: 6980 6990 (+10) 467 zygote64: 10410 10640 (+230) 468 zygote: 10410 10640 (+230) 469 system_server: 15350 15150 (-200) 470 bootanimation ends at: 33790 31230 (-2560) 471 472 473 Systrace 474 -------- 475 Systrace [1] can be used for obtaining performance analysis reports during boot 476 time on userdebug or eng builds. 477 Here is an example of trace events of "wm" and "am" categories: 478 479 $ANDROID_BUILD_TOP/external/chromium-trace/systrace.py wm am --boot 480 481 This command will cause the device to reboot. After the device is rebooted and 482 the boot sequence has finished, the trace report is obtained from the device 483 and written as trace.html on the host by hitting Ctrl+C. 484 485 LIMITATION 486 Recording trace events is started after persistent properties are loaded, so 487 the trace events that are emitted before that are not recorded. Several 488 services such as vold, surfaceflinger, and servicemanager are affected by this 489 limitation since they are started before persistent properties are loaded. 490 Zygote initialization and the processes that are forked from the zygote are not 491 affected. 492 493 [1] http://developer.android.com/tools/help/systrace.html 494 495 496 Debugging init 497 -------------- 498 By default, programs executed by init will drop stdout and stderr into 499 /dev/null. To help with debugging, you can execute your program via the 500 Android program logwrapper. This will redirect stdout/stderr into the 501 Android logging system (accessed via logcat). 502 503 For example 504 service akmd /system/bin/logwrapper /sbin/akmd 505 506 For quicker turnaround when working on init itself, use: 507 508 mm -j 509 m ramdisk-nodeps 510 m bootimage-nodeps 511 adb reboot bootloader 512 fastboot boot $ANDROID_PRODUCT_OUT/boot.img 513 514 Alternatively, use the emulator: 515 516 emulator -partition-size 1024 -verbose -show-kernel -no-window 517 518 You might want to call klog_set_level(6) after the klog_init() call 519 so you see the kernel logging in dmesg (or the emulator output). 520
