README.md
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
15System properties can be expanded using the syntax
16`${property.name}`. This also works in contexts where concatenation is
17required, such as `import /init.recovery.${ro.hardware}.rc`.
18
19Actions and Services implicitly declare a new section. All commands
20or options belong to the section most recently declared. Commands
21or options before the first section are ignored.
22
23Services have unique names. If a second Service is defined
24with the same name as an existing one, it is ignored and an error
25message is logged.
26
27
28Init .rc Files
29--------------
30The init language is used in plain text files that take the .rc file
31extension. There are typically multiple of these in multiple
32locations on the system, described below.
33
34/init.rc is the primary .rc file and is loaded by the init executable
35at the beginning of its execution. It is responsible for the initial
36set up of the system.
37
38Init loads all of the files contained within the
39/{system,vendor,odm}/etc/init/ directories immediately after loading
40the primary /init.rc. This is explained in more details in the
41Imports section of this file.
42
43Legacy devices without the first stage mount mechanism previously were
44able to import init scripts during mount_all, however that is deprecated
45and not allowed for devices launching after Q.
46
47The intention of these directories is:
48
49 1. /system/etc/init/ is for core system items such as
50 SurfaceFlinger, MediaService, and logd.
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 userdebug 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
81Actions
82-------
83Actions are named sequences of commands. Actions have a trigger which
84is used to determine when the action is executed. When an event
85occurs which matches an action's trigger, that action is added to
86the tail of a to-be-executed queue (unless it is already on the
87queue).
88
89Each action in the queue is dequeued in sequence and each command in
90that action is executed in sequence. Init handles other activities
91(device creation/destruction, property setting, process restarting)
92"between" the execution of the commands in activities.
93
94Actions take the form of:
95
96 on <trigger> [&& <trigger>]*
97 <command>
98 <command>
99 <command>
100
101Actions are added to the queue and executed based on the order that
102the file that contains them was parsed (see the Imports section), then
103sequentially within an individual file.
104
105For example if a file contains:
106
107 on boot
108 setprop a 1
109 setprop b 2
110
111 on boot && property:true=true
112 setprop c 1
113 setprop d 2
114
115 on boot
116 setprop e 1
117 setprop f 2
118
119Then when the `boot` trigger occurs and assuming the property `true`
120equals `true`, then the order of the commands executed will be:
121
122 setprop a 1
123 setprop b 2
124 setprop c 1
125 setprop d 2
126 setprop e 1
127 setprop f 2
128
129
130Services
131--------
132Services are programs which init launches and (optionally) restarts
133when they exit. Services take the form of:
134
135 service <name> <pathname> [ <argument> ]*
136 <option>
137 <option>
138 ...
139
140
141Options
142-------
143Options are modifiers to services. They affect how and when init
144runs the service.
145
146`capabilities [ <capability>\* ]`
147> Set capabilities when exec'ing this service. 'capability' should be a Linux
148 capability without the "CAP\_" prefix, like "NET\_ADMIN" or "SETPCAP". See
149 http://man7.org/linux/man-pages/man7/capabilities.7.html for a list of Linux
150 capabilities.
151 If no capabilities are provided, then all capabilities are removed from this service, even if it
152 runs as root.
153
154`class <name> [ <name>\* ]`
155> Specify class names for the service. All services in a
156 named class may be started or stopped together. A service
157 is in the class "default" if one is not specified via the
158 class option. Additional classnames beyond the (required) first
159 one are used to group services.
160 The `animation` class should include all services necessary for both
161 boot animation and shutdown animation. As these services can be
162 launched very early during bootup and can run until the last stage
163 of shutdown, access to /data partition is not guaranteed. These
164 services can check files under /data but it should not keep files opened
165 and should work when /data is not available.
166
167`console [<console>]`
168> This service needs a console. The optional second parameter chooses a
169 specific console instead of the default. The default "/dev/console" can
170 be changed by setting the "androidboot.console" kernel parameter. In
171 all cases the leading "/dev/" should be omitted, so "/dev/tty0" would be
172 specified as just "console tty0".
173 This option connects stdin, stdout, and stderr to the console. It is mutually exclusive with the
174 stdio_to_kmsg option, which only connects stdout and stderr to kmsg.
175
176`critical`
177> This is a device-critical service. If it exits more than four times in
178 four minutes or before boot completes, the device will reboot into bootloader.
179
180`disabled`
181> This service will not automatically start with its class.
182 It must be explicitly started by name or by interface name.
183
184`enter_namespace <type> <path>`
185> Enters the namespace of type _type_ located at _path_. Only network namespaces are supported with
186 _type_ set to "net". Note that only one namespace of a given _type_ may be entered.
187
188`file <path> <type>`
189> Open a file path and pass its fd to the launched process. _type_ must be
190 "r", "w" or "rw". For native executables see libcutils
191 android\_get\_control\_file().
192
193`group <groupname> [ <groupname>\* ]`
194> Change to 'groupname' before exec'ing this service. Additional
195 groupnames beyond the (required) first one are used to set the
196 supplemental groups of the process (via setgroups()).
197 Currently defaults to root. (??? probably should default to nobody)
198
199`interface <interface name> <instance name>`
200> Associates this service with a list of the AIDL or HIDL services that it provides. The interface
201 name must be a fully-qualified name and not a value name. For instance, this is used to allow
202 servicemanager or hwservicemanager to lazily start services. When multiple interfaces are served,
203 this tag should be used multiple times. An example of an entry for a HIDL
204 interface is `interface vendor.foo.bar@1.0::IBaz default`. For an AIDL interface, use
205 `interface aidl <instance name>`. The instance name for an AIDL interface is
206 whatever is registered with servicemanager, and these can be listed with `adb
207 shell dumpsys -l`.
208
209`ioprio <class> <priority>`
210> Sets the IO priority and IO priority class for this service via the SYS_ioprio_set syscall.
211 _class_ must be one of "rt", "be", or "idle". _priority_ must be an integer in the range 0 - 7.
212
213`keycodes <keycode> [ <keycode>\* ]`
214> Sets the keycodes that will trigger this service. If all of the keys corresponding to the passed
215 keycodes are pressed at once, the service will start. This is typically used to start the
216 bugreport service.
217
218> This option may take a property instead of a list of keycodes. In this case, only one option is
219 provided: the property name in the typical property expansion format. The property must contain
220 a comma separated list of keycode values or the text 'none' to indicate that
221 this service does not respond to keycodes.
222
223> For example, `keycodes ${some.property.name:-none}` where some.property.name expands
224 to "123,124,125". Since keycodes are handled very early in init,
225 only PRODUCT_DEFAULT_PROPERTY_OVERRIDES properties can be used.
226
227`memcg.limit_in_bytes <value>` and `memcg.limit_percent <value>`
228> Sets the child's memory.limit_in_bytes to the minimum of `limit_in_bytes`
229 bytes and `limit_percent` which is interpreted as a percentage of the size
230 of the device's physical memory (only if memcg is mounted).
231 Values must be equal or greater than 0.
232
233`memcg.limit_property <value>`
234> Sets the child's memory.limit_in_bytes to the value of the specified property
235 (only if memcg is mounted). This property will override the values specified
236 via `memcg.limit_in_bytes` and `memcg.limit_percent`.
237
238`memcg.soft_limit_in_bytes <value>`
239> Sets the child's memory.soft_limit_in_bytes to the specified value (only if memcg is mounted),
240 which must be equal or greater than 0.
241
242`memcg.swappiness <value>`
243> Sets the child's memory.swappiness to the specified value (only if memcg is mounted),
244 which must be equal or greater than 0.
245
246`namespace <pid|mnt>`
247> Enter a new PID or mount namespace when forking the service.
248
249`oneshot`
250> Do not restart the service when it exits.
251
252`onrestart`
253> Execute a Command (see below) when service restarts.
254
255`oom_score_adjust <value>`
256> Sets the child's /proc/self/oom\_score\_adj to the specified value,
257 which must range from -1000 to 1000.
258
259`override`
260> Indicates that this service definition is meant to override a previous definition for a service
261 with the same name. This is typically meant for services on /odm to override those defined on
262 /vendor. The last service definition that init parses with this keyword is the service definition
263 will use for this service. Pay close attention to the order in which init.rc files are parsed,
264 since it has some peculiarities for backwards compatibility reasons. The 'imports' section of
265 this file has more details on the order.
266
267`priority <priority>`
268> Scheduling priority of the service process. This value has to be in range
269 -20 to 19. Default priority is 0. Priority is set via setpriority().
270
271`reboot_on_failure <target>`
272> If this process cannot be started or if the process terminates with an exit code other than
273 CLD_EXITED or an status other than '0', reboot the system with the target specified in
274 _target_. _target_ takes the same format as the parameter to sys.powerctl. This is particularly
275 intended to be used with the `exec_start` builtin for any must-have checks during boot.
276
277`restart_period <seconds>`
278> If a non-oneshot service exits, it will be restarted at its start time plus
279 this period. It defaults to 5s to rate limit crashing services.
280 This can be increased for services that are meant to run periodically. For
281 example, it may be set to 3600 to indicate that the service should run every hour
282 or 86400 to indicate that the service should run every day.
283
284`rlimit <resource> <cur> <max>`
285> This applies the given rlimit to the service. rlimits are inherited by child
286 processes, so this effectively applies the given rlimit to the process tree
287 started by this service.
288 It is parsed similarly to the setrlimit command specified below.
289
290`seclabel <seclabel>`
291> Change to 'seclabel' before exec'ing this service.
292 Primarily for use by services run from the rootfs, e.g. ueventd, adbd.
293 Services on the system partition can instead use policy-defined transitions
294 based on their file security context.
295 If not specified and no transition is defined in policy, defaults to the init context.
296
297`setenv <name> <value>`
298> Set the environment variable _name_ to _value_ in the launched process.
299
300`shutdown <shutdown_behavior>`
301> Set shutdown behavior of the service process. When this is not specified,
302 the service is killed during shutdown process by using SIGTERM and SIGKILL.
303 The service with shutdown_behavior of "critical" is not killed during shutdown
304 until shutdown times out. When shutdown times out, even services tagged with
305 "shutdown critical" will be killed. When the service tagged with "shutdown critical"
306 is not running when shut down starts, it will be started.
307
308`sigstop`
309> Send SIGSTOP to the service immediately before exec is called. This is intended for debugging.
310 See the below section on debugging for how this can be used.
311
312`socket <name> <type> <perm> [ <user> [ <group> [ <seclabel> ] ] ]`
313> Create a UNIX domain socket named /dev/socket/_name_ and pass its fd to the
314 launched process. _type_ must be "dgram", "stream" or "seqpacket". _type_
315 may end with "+passcred" to enable SO_PASSCRED on the socket. User and
316 group default to 0. 'seclabel' is the SELinux security context for the
317 socket. It defaults to the service security context, as specified by
318 seclabel or computed based on the service executable file security context.
319 For native executables see libcutils android\_get\_control\_socket().
320
321`stdio_to_kmsg`
322> Redirect stdout and stderr to /dev/kmsg_debug. This is useful for services that do not use native
323 Android logging during early boot and whose logs messages we want to capture. This is only enabled
324 when /dev/kmsg_debug is enabled, which is only enabled on userdebug and eng builds.
325 This is mutually exclusive with the console option, which additionally connects stdin to the
326 given console.
327
328`task_profiles <profile> [ <profile>\* ]`
329> Set task profiles for the process when it forks. This is designed to replace the use of
330 writepid option for moving a process into a cgroup.
331
332`timeout_period <seconds>`
333> Provide a timeout after which point the service will be killed. The oneshot keyword is respected
334 here, so oneshot services do not automatically restart, however all other services will.
335 This is particularly useful for creating a periodic service combined with the restart_period
336 option described above.
337
338`updatable`
339> Mark that the service can be overridden (via the 'override' option) later in
340 the boot sequence by APEXes. When a service with updatable option is started
341 before APEXes are all activated, the execution is delayed until the activation
342 is finished. A service that is not marked as updatable cannot be overridden by
343 APEXes.
344
345`user <username>`
346> Change to 'username' before exec'ing this service.
347 Currently defaults to root. (??? probably should default to nobody)
348 As of Android M, processes should use this option even if they
349 require Linux capabilities. Previously, to acquire Linux
350 capabilities, a process would need to run as root, request the
351 capabilities, then drop to its desired uid. There is a new
352 mechanism through fs\_config that allows device manufacturers to add
353 Linux capabilities to specific binaries on a file system that should
354 be used instead. This mechanism is described on
355 <http://source.android.com/devices/tech/config/filesystem.html>. When
356 using this new mechanism, processes can use the user option to
357 select their desired uid without ever running as root.
358 As of Android O, processes can also request capabilities directly in their .rc
359 files. See the "capabilities" option below.
360
361`writepid <file> [ <file>\* ]`
362> Write the child's pid to the given files when it forks. Meant for
363 cgroup/cpuset usage. If no files under /dev/cpuset/ are specified, but the
364 system property 'ro.cpuset.default' is set to a non-empty cpuset name (e.g.
365 '/foreground'), then the pid is written to file /dev/cpuset/_cpuset\_name_/tasks.
366 The use of this option for moving a process into a cgroup is obsolete. Please
367 use task_profiles option instead.
368
369
370Triggers
371--------
372Triggers are strings which can be used to match certain kinds of
373events and used to cause an action to occur.
374
375Triggers are subdivided into event triggers and property triggers.
376
377Event triggers are strings triggered by the 'trigger' command or by
378the QueueEventTrigger() function within the init executable. These
379take the form of a simple string such as 'boot' or 'late-init'.
380
381Property triggers are strings triggered when a named property changes
382value to a given new value or when a named property changes value to
383any new value. These take the form of 'property:<name>=<value>' and
384'property:<name>=\*' respectively. Property triggers are additionally
385evaluated and triggered accordingly during the initial boot phase of
386init.
387
388An Action can have multiple property triggers but may only have one
389event trigger.
390
391For example:
392`on boot && property:a=b` defines an action that is only executed when
393the 'boot' event trigger happens and the property a equals b.
394
395`on property:a=b && property:c=d` defines an action that is executed
396at three times:
397
398 1. During initial boot if property a=b and property c=d.
399 2. Any time that property a transitions to value b, while property c already equals d.
400 3. Any time that property c transitions to value d, while property a already equals b.
401
402
403Commands
404--------
405
406`bootchart [start|stop]`
407> Start/stop bootcharting. These are present in the default init.rc files,
408 but bootcharting is only active if the file /data/bootchart/enabled exists;
409 otherwise bootchart start/stop are no-ops.
410
411`chmod <octal-mode> <path>`
412> Change file access permissions.
413
414`chown <owner> <group> <path>`
415> Change file owner and group.
416
417`class_start <serviceclass>`
418> Start all services of the specified class if they are
419 not already running. See the start entry for more information on
420 starting services.
421
422`class_start_post_data <serviceclass>`
423> Like `class_start`, but only considers services that were started
424 after /data was mounted, and that were running at the time
425 `class_reset_post_data` was called. Only used for FDE devices.
426
427`class_stop <serviceclass>`
428> Stop and disable all services of the specified class if they are
429 currently running.
430
431`class_reset <serviceclass>`
432> Stop all services of the specified class if they are
433 currently running, without disabling them. They can be restarted
434 later using `class_start`.
435
436`class_reset_post_data <serviceclass>`
437> Like `class_reset`, but only considers services that were started
438 after /data was mounted. Only used for FDE devices.
439
440`class_restart <serviceclass>`
441> Restarts all services of the specified class.
442
443`copy <src> <dst>`
444> Copies a file. Similar to write, but useful for binary/large
445 amounts of data.
446 Regarding to the src file, copying from symbolic link file and world-writable
447 or group-writable files are not allowed.
448 Regarding to the dst file, the default mode created is 0600 if it does not
449 exist. And it will be truncated if dst file is a normal regular file and
450 already exists.
451
452`domainname <name>`
453> Set the domain name.
454
455`enable <servicename>`
456> Turns a disabled service into an enabled one as if the service did not
457 specify disabled.
458 If the service is supposed to be running, it will be started now.
459 Typically used when the bootloader sets a variable that indicates a specific
460 service should be started when needed. E.g.
461
462 on property:ro.boot.myfancyhardware=1
463 enable my_fancy_service_for_my_fancy_hardware
464
465`exec [ <seclabel> [ <user> [ <group>\* ] ] ] -- <command> [ <argument>\* ]`
466> Fork and execute command with the given arguments. The command starts
467 after "--" so that an optional security context, user, and supplementary
468 groups can be provided. No other commands will be run until this one
469 finishes. _seclabel_ can be a - to denote default. Properties are expanded
470 within _argument_.
471 Init halts executing commands until the forked process exits.
472
473`exec_background [ <seclabel> [ <user> [ <group>\* ] ] ] -- <command> [ <argument>\* ]`
474> Fork and execute command with the given arguments. This is handled similarly
475 to the `exec` command. The difference is that init does not halt executing
476 commands until the process exits for `exec_background`.
477
478`exec_start <service>`
479> Start a given service and halt the processing of additional init commands
480 until it returns. The command functions similarly to the `exec` command,
481 but uses an existing service definition in place of the exec argument vector.
482
483`export <name> <value>`
484> Set the environment variable _name_ equal to _value_ in the
485 global environment (which will be inherited by all processes
486 started after this command is executed)
487
488`hostname <name>`
489> Set the host name.
490
491`ifup <interface>`
492> Bring the network interface _interface_ online.
493
494`insmod [-f] <path> [<options>]`
495> Install the module at _path_ with the specified options.
496 -f: force installation of the module even if the version of the running kernel
497 and the version of the kernel for which the module was compiled do not match.
498
499`interface_start <name>` \
500`interface_restart <name>` \
501`interface_stop <name>`
502> Find the service that provides the interface _name_ if it exists and run the `start`, `restart`,
503or `stop` commands on it respectively. _name_ may be either a fully qualified HIDL name, in which
504case it is specified as `<interface>/<instance>`, or an AIDL name, in which case it is specified as
505`aidl/<interface>` for example `android.hardware.secure_element@1.1::ISecureElement/eSE1` or
506`aidl/aidl_lazy_test_1`.
507
508> Note that these commands only act on interfaces specified by the `interface` service option, not
509on interfaces registered at runtime.
510
511> Example usage of these commands: \
512`interface_start android.hardware.secure_element@1.1::ISecureElement/eSE1`
513will start the HIDL Service that provides the `android.hardware.secure_element@1.1` and `eSI1`
514instance. \
515`interface_start aidl/aidl_lazy_test_1` will start the AIDL service that
516provides the `aidl_lazy_test_1` interface.
517
518`load_system_props`
519> (This action is deprecated and no-op.)
520
521`load_persist_props`
522> Loads persistent properties when /data has been decrypted.
523 This is included in the default init.rc.
524
525`loglevel <level>`
526> Sets init's log level to the integer level, from 7 (all logging) to 0
527 (fatal logging only). The numeric values correspond to the kernel log
528 levels, but this command does not affect the kernel log level. Use the
529 `write` command to write to `/proc/sys/kernel/printk` to change that.
530 Properties are expanded within _level_.
531
532`mark_post_data`
533> Used to mark the point right after /data is mounted. Used to implement the
534 `class_reset_post_data` and `class_start_post_data` commands.
535
536`mkdir <path> [<mode>] [<owner>] [<group>] [encryption=<action>] [key=<key>]`
537> Create a directory at _path_, optionally with the given mode, owner, and
538 group. If not provided, the directory is created with permissions 755 and
539 owned by the root user and root group. If provided, the mode, owner and group
540 will be updated if the directory exists already.
541
542 > _action_ can be one of:
543 * `None`: take no encryption action; directory will be encrypted if parent is.
544 * `Require`: encrypt directory, abort boot process if encryption fails
545 * `Attempt`: try to set an encryption policy, but continue if it fails
546 * `DeleteIfNecessary`: recursively delete directory if necessary to set
547 encryption policy.
548
549 > _key_ can be one of:
550 * `ref`: use the systemwide DE key
551 * `per_boot_ref`: use the key freshly generated on each boot.
552
553`mount_all [ <fstab> ] [--<option>]`
554> Calls fs\_mgr\_mount\_all on the given fs\_mgr-format fstab with optional
555 options "early" and "late".
556 With "--early" set, the init executable will skip mounting entries with
557 "latemount" flag and triggering fs encryption state event. With "--late" set,
558 init executable will only mount entries with "latemount" flag. By default,
559 no option is set, and mount\_all will process all entries in the given fstab.
560 If the fstab parameter is not specified, fstab.${ro.boot.fstab_suffix},
561 fstab.${ro.hardware} or fstab.${ro.hardware.platform} will be scanned for
562 under /odm/etc, /vendor/etc, or / at runtime, in that order.
563
564`mount <type> <device> <dir> [ <flag>\* ] [<options>]`
565> Attempt to mount the named device at the directory _dir_
566 _flag_s include "ro", "rw", "remount", "noatime", ...
567 _options_ include "barrier=1", "noauto\_da\_alloc", "discard", ... as
568 a comma separated string, e.g. barrier=1,noauto\_da\_alloc
569
570`perform_apex_config`
571> Performs tasks after APEXes are mounted. For example, creates data directories
572 for the mounted APEXes, parses config file(s) from them, and updates linker
573 configurations. Intended to be used only once when apexd notifies the mount
574 event by setting `apexd.status` to ready.
575
576`restart <service>`
577> Stops and restarts a running service, does nothing if the service is currently
578 restarting, otherwise, it just starts the service.
579
580`restorecon <path> [ <path>\* ]`
581> Restore the file named by _path_ to the security context specified
582 in the file\_contexts configuration.
583 Not required for directories created by the init.rc as these are
584 automatically labeled correctly by init.
585
586`restorecon_recursive <path> [ <path>\* ]`
587> Recursively restore the directory tree named by _path_ to the
588 security contexts specified in the file\_contexts configuration.
589
590`rm <path>`
591> Calls unlink(2) on the given path. You might want to
592 use "exec -- rm ..." instead (provided the system partition is
593 already mounted).
594
595`rmdir <path>`
596> Calls rmdir(2) on the given path.
597
598`readahead <file|dir> [--fully]`
599> Calls readahead(2) on the file or files within given directory.
600 Use option --fully to read the full file content.
601
602`setprop <name> <value>`
603> Set system property _name_ to _value_. Properties are expanded
604 within _value_.
605
606`setrlimit <resource> <cur> <max>`
607> Set the rlimit for a resource. This applies to all processes launched after
608 the limit is set. It is intended to be set early in init and applied globally.
609 _resource_ is best specified using its text representation ('cpu', 'rtio', etc
610 or 'RLIM_CPU', 'RLIM_RTIO', etc). It also may be specified as the int value
611 that the resource enum corresponds to.
612 _cur_ and _max_ can be 'unlimited' or '-1' to indicate an infinite rlimit.
613
614`start <service>`
615> Start a service running if it is not already running.
616 Note that this is _not_ synchronous, and even if it were, there is
617 no guarantee that the operating system's scheduler will execute the
618 service sufficiently to guarantee anything about the service's status.
619 See the `exec_start` command for a synchronous version of `start`.
620
621> This creates an important consequence that if the service offers
622 functionality to other services, such as providing a
623 communication channel, simply starting this service before those
624 services is _not_ sufficient to guarantee that the channel has
625 been set up before those services ask for it. There must be a
626 separate mechanism to make any such guarantees.
627
628`stop <service>`
629> Stop a service from running if it is currently running.
630
631`swapon_all [ <fstab> ]`
632> Calls fs\_mgr\_swapon\_all on the given fstab file.
633 If the fstab parameter is not specified, fstab.${ro.boot.fstab_suffix},
634 fstab.${ro.hardware} or fstab.${ro.hardware.platform} will be scanned for
635 under /odm/etc, /vendor/etc, or / at runtime, in that order.
636
637`symlink <target> <path>`
638> Create a symbolic link at _path_ with the value _target_
639
640`sysclktz <minutes_west_of_gmt>`
641> Set the system clock base (0 if system clock ticks in GMT)
642
643`trigger <event>`
644> Trigger an event. Used to queue an action from another
645 action.
646
647`umount <path>`
648> Unmount the filesystem mounted at that path.
649
650`umount_all [ <fstab> ]`
651> Calls fs\_mgr\_umount\_all on the given fstab file.
652 If the fstab parameter is not specified, fstab.${ro.boot.fstab_suffix},
653 fstab.${ro.hardware} or fstab.${ro.hardware.platform} will be scanned for
654 under /odm/etc, /vendor/etc, or / at runtime, in that order.
655
656`verity_update_state <mount-point>`
657> Internal implementation detail used to update dm-verity state and
658 set the partition._mount-point_.verified properties used by adb remount
659 because fs\_mgr can't set them directly itself.
660
661`wait <path> [ <timeout> ]`
662> Poll for the existence of the given file and return when found,
663 or the timeout has been reached. If timeout is not specified it
664 currently defaults to five seconds. The timeout value can be
665 fractional seconds, specified in floating point notation.
666
667`wait_for_prop <name> <value>`
668> Wait for system property _name_ to be _value_. Properties are expanded
669 within _value_. If property _name_ is already set to _value_, continue
670 immediately.
671
672`write <path> <content>`
673> Open the file at _path_ and write a string to it with write(2).
674 If the file does not exist, it will be created. If it does exist,
675 it will be truncated. Properties are expanded within _content_.
676
677
678Imports
679-------
680`import <path>`
681> Parse an init config file, extending the current configuration.
682 If _path_ is a directory, each file in the directory is parsed as
683 a config file. It is not recursive, nested directories will
684 not be parsed.
685
686The import keyword is not a command, but rather its own section,
687meaning that it does not happen as part of an Action, but rather,
688imports are handled as a file is being parsed and follow the below logic.
689
690There are only three times where the init executable imports .rc files:
691
692 1. When it imports /init.rc or the script indicated by the property
693 `ro.boot.init_rc` during initial boot.
694 2. When it imports /{system,vendor,odm}/etc/init/ for first stage mount
695 devices immediately after importing /init.rc.
696 3. (Deprecated) When it imports /{system,vendor,odm}/etc/init/ or .rc files
697 at specified paths during mount_all, not allowed for devices launching
698 after Q.
699
700The order that files are imported is a bit complex for legacy reasons
701and to keep backwards compatibility. It is not strictly guaranteed.
702
703The only correct way to guarantee that a command has been run before a
704different command is to either 1) place it in an Action with an
705earlier executed trigger, or 2) place it in an Action with the same
706trigger within the same file at an earlier line.
707
708Nonetheless, the de facto order for first stage mount devices is:
7091. /init.rc is parsed then recursively each of its imports are
710 parsed.
7112. The contents of /system/etc/init/ are alphabetized and parsed
712 sequentially, with imports happening recursively after each file is
713 parsed.
7143. Step 2 is repeated for /vendor/etc/init then /odm/etc/init
715
716The below pseudocode may explain this more clearly:
717
718 fn Import(file)
719 Parse(file)
720 for (import : file.imports)
721 Import(import)
722
723 Import(/init.rc)
724 Directories = [/system/etc/init, /vendor/etc/init, /odm/etc/init]
725 for (directory : Directories)
726 files = <Alphabetical order of directory's contents>
727 for (file : files)
728 Import(file)
729
730
731Properties
732----------
733Init provides state information with the following properties.
734
735`init.svc.<name>`
736> State of a named service ("stopped", "stopping", "running", "restarting")
737
738`dev.mnt.blk.<mount_point>`
739> Block device base name associated with a *mount_point*.
740 The *mount_point* has / replaced by . and if referencing the root mount point
741 "/", it will use "/root", specifically `dev.mnt.blk.root`.
742 Meant for references to `/sys/device/block/${dev.mnt.blk.<mount_point>}/` and
743 `/sys/fs/ext4/${dev.mnt.blk.<mount_point>}/` to tune the block device
744 characteristics in a device agnostic manner.
745
746Init responds to properties that begin with `ctl.`. These properties take the format of
747`ctl.[<target>_]<command>` and the _value_ of the system property is used as a parameter. The
748_target_ is optional and specifies the service option that _value_ is meant to match with. There is
749only one option for _target_, `interface` which indicates that _value_ will refer to an interface
750that a service provides and not the service name itself.
751
752For example:
753
754`SetProperty("ctl.start", "logd")` will run the `start` command on `logd`.
755
756`SetProperty("ctl.interface_start", "aidl/aidl_lazy_test_1")` will run the `start` command on the
757service that exposes the `aidl aidl_lazy_test_1` interface.
758
759Note that these
760properties are only settable; they will have no value when read.
761
762The _commands_ are listed below.
763
764`start` \
765`restart` \
766`stop` \
767These are equivalent to using the `start`, `restart`, and `stop` commands on the service specified
768by the _value_ of the property.
769
770`oneshot_on` and `oneshot_off` will turn on or off the _oneshot_
771flag for the service specified by the _value_ of the property. This is
772particularly intended for services that are conditionally lazy HALs. When
773they are lazy HALs, oneshot must be on, otherwise oneshot should be off.
774
775`sigstop_on` and `sigstop_off` will turn on or off the _sigstop_ feature for the service
776specified by the _value_ of the property. See the _Debugging init_ section below for more details
777about this feature.
778
779Boot timing
780-----------
781Init records some boot timing information in system properties.
782
783`ro.boottime.init`
784> Time after boot in ns (via the CLOCK\_BOOTTIME clock) at which the first
785 stage of init started.
786
787`ro.boottime.init.first_stage`
788> How long in ns it took to run first stage.
789
790`ro.boottime.init.selinux`
791> How long in ns it took to run SELinux stage.
792
793`ro.boottime.init.cold_boot_wait`
794> How long init waited for ueventd's coldboot phase to end.
795
796`ro.boottime.<service-name>`
797> Time after boot in ns (via the CLOCK\_BOOTTIME clock) that the service was
798 first started.
799
800
801Bootcharting
802------------
803This version of init contains code to perform "bootcharting": generating log
804files that can be later processed by the tools provided by <http://www.bootchart.org/>.
805
806On the emulator, use the -bootchart _timeout_ option to boot with bootcharting
807activated for _timeout_ seconds.
808
809On a device:
810
811 adb shell 'touch /data/bootchart/enabled'
812
813Don't forget to delete this file when you're done collecting data!
814
815The log files are written to /data/bootchart/. A script is provided to
816retrieve them and create a bootchart.tgz file that can be used with the
817bootchart command-line utility:
818
819 sudo apt-get install pybootchartgui
820 # grab-bootchart.sh uses $ANDROID_SERIAL.
821 $ANDROID_BUILD_TOP/system/core/init/grab-bootchart.sh
822
823One thing to watch for is that the bootchart will show init as if it started
824running at 0s. You'll have to look at dmesg to work out when the kernel
825actually started init.
826
827
828Comparing two bootcharts
829------------------------
830A handy script named compare-bootcharts.py can be used to compare the
831start/end time of selected processes. The aforementioned grab-bootchart.sh
832will leave a bootchart tarball named bootchart.tgz at /tmp/android-bootchart.
833If two such tarballs are preserved on the host machine under different
834directories, the script can list the timestamps differences. For example:
835
836Usage: system/core/init/compare-bootcharts.py _base-bootchart-dir_ _exp-bootchart-dir_
837
838 process: baseline experiment (delta) - Unit is ms (a jiffy is 10 ms on the system)
839 ------------------------------------
840 /init: 50 40 (-10)
841 /system/bin/surfaceflinger: 4320 4470 (+150)
842 /system/bin/bootanimation: 6980 6990 (+10)
843 zygote64: 10410 10640 (+230)
844 zygote: 10410 10640 (+230)
845 system_server: 15350 15150 (-200)
846 bootanimation ends at: 33790 31230 (-2560)
847
848
849Systrace
850--------
851Systrace (<http://developer.android.com/tools/help/systrace.html>) can be
852used for obtaining performance analysis reports during boot
853time on userdebug or eng builds.
854
855Here is an example of trace events of "wm" and "am" categories:
856
857 $ANDROID_BUILD_TOP/external/chromium-trace/systrace.py \
858 wm am --boot
859
860This command will cause the device to reboot. After the device is rebooted and
861the boot sequence has finished, the trace report is obtained from the device
862and written as trace.html on the host by hitting Ctrl+C.
863
864Limitation: recording trace events is started after persistent properties are loaded, so
865the trace events that are emitted before that are not recorded. Several
866services such as vold, surfaceflinger, and servicemanager are affected by this
867limitation since they are started before persistent properties are loaded.
868Zygote initialization and the processes that are forked from the zygote are not
869affected.
870
871
872Debugging init
873--------------
874When a service starts from init, it may fail to `execv()` the service. This is not typical, and may
875point to an error happening in the linker as the new service is started. The linker in Android
876prints its logs to `logd` and `stderr`, so they are visible in `logcat`. If the error is encountered
877before it is possible to access `logcat`, the `stdio_to_kmsg` service option may be used to direct
878the logs that the linker prints to `stderr` to `kmsg`, where they can be read via a serial port.
879
880Launching init services without init is not recommended as init sets up a significant amount of
881environment (user, groups, security label, capabilities, etc) that is hard to replicate manually.
882
883If it is required to debug a service from its very start, the `sigstop` service option is added.
884This option will send SIGSTOP to a service immediately before calling exec. This gives a window
885where developers can attach a debugger, strace, etc before continuing the service with SIGCONT.
886
887This flag can also be dynamically controlled via the ctl.sigstop_on and ctl.sigstop_off properties.
888
889Below is an example of dynamically debugging logd via the above:
890
891 stop logd
892 setprop ctl.sigstop_on logd
893 start logd
894 ps -e | grep logd
895 > logd 4343 1 18156 1684 do_signal_stop 538280 T init
896 gdbclient.py -p 4343
897 b main
898 c
899 c
900 c
901 > Breakpoint 1, main (argc=1, argv=0x7ff8c9a488) at system/core/logd/main.cpp:427
902
903Below is an example of doing the same but with strace
904
905 stop logd
906 setprop ctl.sigstop_on logd
907 start logd
908 ps -e | grep logd
909 > logd 4343 1 18156 1684 do_signal_stop 538280 T init
910 strace -p 4343
911
912 (From a different shell)
913 kill -SIGCONT 4343
914
915 > strace runs
916
917Host Init Script Verification
918-----------------------------
919
920Init scripts are checked for correctness during build time. Specifically the below is checked.
921
9221) Well formatted action, service and import sections, e.g. no actions without a preceding 'on'
923line, and no extraneous lines after an 'import' statement.
9242) All commands map to a valid keyword and the argument count is within the correct range.
9253) All service options are valid. This is stricter than how commands are checked as the service
926options' arguments are fully parsed, e.g. UIDs and GIDs must resolve.
927
928There are other parts of init scripts that are only parsed at runtime and therefore not checked
929during build time, among them are the below.
930
9311) The validity of the arguments of commands, e.g. no checking if file paths actually exist, if
932SELinux would permit the operation, or if the UIDs and GIDs resolve.
9332) No checking if a service exists or has a valid SELinux domain defined
9343) No checking if a service has not been previously defined in a different init script.
935
936Early Init Boot Sequence
937------------------------
938The early init boot sequence is broken up into three stages: first stage init, SELinux setup, and
939second stage init.
940
941First stage init is responsible for setting up the bare minimum requirements to load the rest of the
942system. Specifically this includes mounting /dev, /proc, mounting 'early mount' partitions (which
943needs to include all partitions that contain system code, for example system and vendor), and moving
944the system.img mount to / for devices with a ramdisk.
945
946Note that in Android Q, system.img always contains TARGET_ROOT_OUT and always is mounted at / by the
947time first stage init finishes. Android Q will also require dynamic partitions and therefore will
948require using a ramdisk to boot Android. The recovery ramdisk can be used to boot to Android instead
949of a dedicated ramdisk as well.
950
951First stage init has three variations depending on the device configuration:
9521) For system-as-root devices, first stage init is part of /system/bin/init and a symlink at /init
953points to /system/bin/init for backwards compatibility. These devices do not need to do anything to
954mount system.img, since it is by definition already mounted as the rootfs by the kernel.
955
9562) For devices with a ramdisk, first stage init is a static executable located at /init. These
957devices mount system.img as /system then perform a switch root operation to move the mount at
958/system to /. The contents of the ramdisk are freed after mounting has completed.
959
9603) For devices that use recovery as a ramdisk, first stage init it contained within the shared init
961located at /init within the recovery ramdisk. These devices first switch root to
962/first_stage_ramdisk to remove the recovery components from the environment, then proceed the same
963as 2). Note that the decision to boot normally into Android instead of booting
964into recovery mode is made if androidboot.force_normal_boot=1 is present in the
965kernel commandline.
966
967Once first stage init finishes it execs /system/bin/init with the "selinux_setup" argument. This
968phase is where SELinux is optionally compiled and loaded onto the system. selinux.cpp contains more
969information on the specifics of this process.
970
971Lastly once that phase finishes, it execs /system/bin/init again with the "second_stage"
972argument. At this point the main phase of init runs and continues the boot process via the init.rc
973scripts.
974