| Android Init Language |
| --------------------- |
| |
| The Android Init Language consists of five broad classes of statements, |
| which are Actions, Commands, Services, Options, and Imports. |
| |
| All of these are line-oriented, consisting of tokens separated by |
| whitespace. The c-style backslash escapes may be used to insert |
| whitespace into a token. Double quotes may also be used to prevent |
| whitespace from breaking text into multiple tokens. The backslash, |
| when it is the last character on a line, may be used for line-folding. |
| |
| Lines which start with a # (leading whitespace allowed) are comments. |
| |
| Actions and Services implicitly declare a new section. All commands |
| or options belong to the section most recently declared. Commands |
| or options before the first section are ignored. |
| |
| Actions and Services have unique names. If a second Action is defined |
| with the same name as an existing one, its commands are appended to |
| the commands of the existing action. If a second Service is defined |
| with the same name as an existing one, it is ignored and an error |
| message is logged. |
| |
| |
| Init .rc Files |
| -------------- |
| The init language is used in plaintext files that take the .rc file |
| extension. These are typically multiple of these in multiple |
| locations on the system, described below. |
| |
| /init.rc is the primary .rc file and is loaded by the init executable |
| at the beginning of its execution. It is responsible for the initial |
| set up of the system. It imports /init.${ro.hardware}.rc which is the |
| primary vendor supplied .rc file. |
| |
| During the mount_all command, the init executable loads all of the |
| files contained within the /{system,vendor,odm}/etc/init/ directories. |
| These directories are intended for all Actions and Services used after |
| file system mounting. |
| |
| One may specify paths in the mount_all command line to have it import |
| .rc files at the specified paths instead of the default ones listed above. |
| This is primarily for supporting factory mode and other non-standard boot |
| modes. The three default paths should be used for the normal boot process. |
| |
| The intention of these directories is as follows |
| 1) /system/etc/init/ is for core system items such as |
| SurfaceFlinger, MediaService, and logcatd. |
| 2) /vendor/etc/init/ is for SoC vendor items such as actions or |
| daemons needed for core SoC functionality. |
| 3) /odm/etc/init/ is for device manufacturer items such as |
| actions or daemons needed for motion sensor or other peripheral |
| functionality. |
| |
| All services whose binaries reside on the system, vendor, or odm |
| partitions should have their service entries placed into a |
| corresponding init .rc file, located in the /etc/init/ |
| directory of the partition where they reside. There is a build |
| system macro, LOCAL_INIT_RC, that handles this for developers. Each |
| init .rc file should additionally contain any actions associated with |
| its service. |
| |
| An example is the logcatd.rc and Android.mk files located in the |
| system/core/logcat directory. The LOCAL_INIT_RC macro in the |
| Android.mk file places logcatd.rc in /system/etc/init/ during the |
| build process. Init loads logcatd.rc during the mount_all command and |
| allows the service to be run and the action to be queued when |
| appropriate. |
| |
| This break up of init .rc files according to their daemon is preferred |
| to the previously used monolithic init .rc files. This approach |
| ensures that the only service entries that init reads and the only |
| actions that init performs correspond to services whose binaries are in |
| fact present on the file system, which was not the case with the |
| monolithic init .rc files. This additionally will aid in merge |
| conflict resolution when multiple services are added to the system, as |
| each one will go into a separate file. |
| |
| There are two options "early" and "late" in mount_all command |
| which can be set after optional paths. With "--early" set, the |
| init executable will skip mounting entries with "latemount" flag |
| and triggering fs encryption state event. With "--late" set, |
| init executable will only mount entries with "latemount" flag but skip |
| importing rc files. By default, no option is set, and mount_all will |
| mount_all will process all entries in the given fstab. |
| |
| Actions |
| ------- |
| Actions are named sequences of commands. Actions have a trigger which |
| is used to determine when the action should occur. When an event |
| occurs which matches an action's trigger, that action is added to |
| the tail of a to-be-executed queue (unless it is already on the |
| queue). |
| |
| Each action in the queue is dequeued in sequence and each command in |
| that action is executed in sequence. Init handles other activities |
| (device creation/destruction, property setting, process restarting) |
| "between" the execution of the commands in activities. |
| |
| Actions take the form of: |
| |
| on <trigger> [&& <trigger>]* |
| <command> |
| <command> |
| <command> |
| |
| |
| Services |
| -------- |
| Services are programs which init launches and (optionally) restarts |
| when they exit. Services take the form of: |
| |
| service <name> <pathname> [ <argument> ]* |
| <option> |
| <option> |
| ... |
| |
| |
| Options |
| ------- |
| Options are modifiers to services. They affect how and when init |
| runs the service. |
| |
| console [<console>] |
| This service needs a console. The optional second parameter chooses a |
| specific console instead of the default. The default "/dev/console" can |
| be changed by setting the "androidboot.console" kernel parameter. In |
| all cases the leading "/dev/" should be omitted, so "/dev/tty0" would be |
| specified as just "console tty0". |
| |
| critical |
| This is a device-critical service. If it exits more than four times in |
| four minutes, the device will reboot into recovery mode. |
| |
| disabled |
| This service will not automatically start with its class. |
| It must be explicitly started by name. |
| |
| setenv <name> <value> |
| Set the environment variable <name> to <value> in the launched process. |
| |
| socket <name> <type> <perm> [ <user> [ <group> [ <seclabel> ] ] ] |
| Create a unix domain socket named /dev/socket/<name> and pass its fd to the |
| launched process. <type> must be "dgram", "stream" or "seqpacket". User and |
| group default to 0. 'seclabel' is the SELinux security context for the |
| socket. It defaults to the service security context, as specified by |
| seclabel or computed based on the service executable file security context. |
| For native executables see libcutils android_get_control_socket(). |
| |
| file <path> <type> <perm> [ <user> [ <group> [ <seclabel> ] ] ] |
| Open/Create a file path and pass its fd to the launched process. <type> must |
| be "r", "w" or "rw". User and group default to 0. 'seclabel' is the SELinux |
| security context for the file if it must be created. It defaults to the |
| service security context, as specified by seclabel or computed based on the |
| service executable file security context. For native executables see |
| libcutils android_get_control_file(). |
| |
| user <username> |
| Change to 'username' before exec'ing this service. |
| Currently defaults to root. (??? probably should default to nobody) |
| As of Android M, processes should use this option even if they |
| require Linux capabilities. Previously, to acquire Linux |
| capabilities, a process would need to run as root, request the |
| capabilities, then drop to its desired uid. There is a new |
| mechanism through fs_config that allows device manufacturers to add |
| Linux capabilities to specific binaries on a file system that should |
| be used instead. This mechanism is described on |
| http://source.android.com/devices/tech/config/filesystem.html. When |
| using this new mechanism, processes can use the user option to |
| select their desired uid without ever running as root. |
| As of Android O, processes can also request capabilities directly in their .rc |
| files. See the "capabilities" option below. |
| |
| group <groupname> [ <groupname> ]* |
| Change to 'groupname' before exec'ing this service. Additional |
| groupnames beyond the (required) first one are used to set the |
| supplemental groups of the process (via setgroups()). |
| Currently defaults to root. (??? probably should default to nobody) |
| |
| capabilities <capability> [ <capability> ]* |
| Set capabilities when exec'ing this service. 'capability' should be a Linux |
| capability without the "CAP_" prefix, like "NET_ADMIN" or "SETPCAP". See |
| http://man7.org/linux/man-pages/man7/capabilities.7.html for a list of Linux |
| capabilities. |
| |
| seclabel <seclabel> |
| Change to 'seclabel' before exec'ing this service. |
| Primarily for use by services run from the rootfs, e.g. ueventd, adbd. |
| Services on the system partition can instead use policy-defined transitions |
| based on their file security context. |
| If not specified and no transition is defined in policy, defaults to the init context. |
| |
| oneshot |
| Do not restart the service when it exits. |
| |
| class <name> |
| Specify a class name for the service. All services in a |
| named class may be started or stopped together. A service |
| is in the class "default" if one is not specified via the |
| class option. |
| |
| onrestart |
| Execute a Command (see below) when service restarts. |
| |
| writepid <file...> |
| Write the child's pid to the given files when it forks. Meant for |
| cgroup/cpuset usage. |
| |
| priority <priority> |
| Scheduling priority of the service process. This value has to be in range |
| -20 to 19. Default priority is 0. Priority is set via setpriority(). |
| |
| namespace <pid|mnt> |
| Enter a new PID or mount namespace when forking the service. |
| |
| oom_score_adjust <value> |
| Sets the child's /proc/self/oom_score_adj to the specified value, |
| which must range from -1000 to 1000. |
| |
| |
| Triggers |
| -------- |
| Triggers are strings which can be used to match certain kinds of |
| events and used to cause an action to occur. |
| |
| Triggers are subdivided into event triggers and property triggers. |
| |
| Event triggers are strings triggered by the 'trigger' command or by |
| the QueueEventTrigger() function within the init executable. These |
| take the form of a simple string such as 'boot' or 'late-init'. |
| |
| Property triggers are strings triggered when a named property changes |
| value to a given new value or when a named property changes value to |
| any new value. These take the form of 'property:<name>=<value>' and |
| 'property:<name>=*' respectively. Property triggers are additionally |
| evaluated and triggered accordingly during the initial boot phase of |
| init. |
| |
| An Action can have multiple property triggers but may only have one |
| event trigger. |
| |
| For example: |
| 'on boot && property:a=b' defines an action that is only executed when |
| the 'boot' event trigger happens and the property a equals b. |
| |
| 'on property:a=b && property:c=d' defines an action that is executed |
| at three times, |
| 1) During initial boot if property a=b and property c=d |
| 2) Any time that property a transitions to value b, while property |
| c already equals d. |
| 3) Any time that property c transitions to value d, while property |
| a already equals b. |
| |
| |
| Commands |
| -------- |
| |
| bootchart_init |
| Start bootcharting if configured (see below). |
| This is included in the default init.rc. |
| |
| chmod <octal-mode> <path> |
| Change file access permissions. |
| |
| chown <owner> <group> <path> |
| Change file owner and group. |
| |
| class_start <serviceclass> |
| Start all services of the specified class if they are |
| not already running. |
| |
| class_stop <serviceclass> |
| Stop and disable all services of the specified class if they are |
| currently running. |
| |
| class_reset <serviceclass> |
| Stop all services of the specified class if they are |
| currently running, without disabling them. They can be restarted |
| later using class_start. |
| |
| copy <src> <dst> |
| Copies a file. Similar to write, but useful for binary/large |
| amounts of data. |
| |
| domainname <name> |
| Set the domain name. |
| |
| enable <servicename> |
| Turns a disabled service into an enabled one as if the service did not |
| specify disabled. |
| If the service is supposed to be running, it will be started now. |
| Typically used when the bootloader sets a variable that indicates a specific |
| service should be started when needed. E.g. |
| on property:ro.boot.myfancyhardware=1 |
| enable my_fancy_service_for_my_fancy_hardware |
| |
| exec [ <seclabel> [ <user> [ <group> ]* ] ] -- <command> [ <argument> ]* |
| Fork and execute command with the given arguments. The command starts |
| after "--" so that an optional security context, user, and supplementary |
| groups can be provided. No other commands will be run until this one |
| finishes. <seclabel> can be a - to denote default. |
| |
| export <name> <value> |
| Set the environment variable <name> equal to <value> in the |
| global environment (which will be inherited by all processes |
| started after this command is executed) |
| |
| hostname <name> |
| Set the host name. |
| |
| ifup <interface> |
| Bring the network interface <interface> online. |
| |
| insmod [-f] <path> [<options>] |
| Install the module at <path> with the specified options. |
| -f |
| Force installation of the module even if the version of the running kernel |
| and the version of the kernel for which the module was compiled do not match. |
| |
| load_all_props |
| Loads properties from /system, /vendor, et cetera. |
| This is included in the default init.rc. |
| |
| load_persist_props |
| Loads persistent properties when /data has been decrypted. |
| This is included in the default init.rc. |
| |
| loglevel <level> |
| Sets the kernel log level to level. Properties are expanded within <level>. |
| |
| mkdir <path> [mode] [owner] [group] |
| Create a directory at <path>, optionally with the given mode, owner, and |
| group. If not provided, the directory is created with permissions 755 and |
| owned by the root user and root group. If provided, the mode, owner and group |
| will be updated if the directory exists already. |
| |
| mount_all <fstab> [ <path> ]* [--<option>] |
| Calls fs_mgr_mount_all on the given fs_mgr-format fstab and imports .rc files |
| at the specified paths (e.g., on the partitions just mounted) with optional |
| options "early" and "late". |
| Refer to the section of "Init .rc Files" for detail. |
| |
| mount <type> <device> <dir> [ <flag> ]* [<options>] |
| Attempt to mount the named device at the directory <dir> |
| <flag>s include "ro", "rw", "remount", "noatime", ... |
| <options> include "barrier=1", "noauto_da_alloc", "discard", ... as |
| a comma separated string, eg: barrier=1,noauto_da_alloc |
| |
| powerctl |
| Internal implementation detail used to respond to changes to the |
| "sys.powerctl" system property, used to implement rebooting. |
| |
| restart <service> |
| Like stop, but doesn't disable the service. |
| |
| restorecon <path> [ <path> ]* |
| Restore the file named by <path> to the security context specified |
| in the file_contexts configuration. |
| Not required for directories created by the init.rc as these are |
| automatically labeled correctly by init. |
| |
| restorecon_recursive <path> [ <path> ]* |
| Recursively restore the directory tree named by <path> to the |
| security contexts specified in the file_contexts configuration. |
| |
| rm <path> |
| Calls unlink(2) on the given path. You might want to |
| use "exec -- rm ..." instead (provided the system partition is |
| already mounted). |
| |
| rmdir <path> |
| Calls rmdir(2) on the given path. |
| |
| setprop <name> <value> |
| Set system property <name> to <value>. Properties are expanded |
| within <value>. |
| |
| setrlimit <resource> <cur> <max> |
| Set the rlimit for a resource. |
| |
| start <service> |
| Start a service running if it is not already running. |
| |
| stop <service> |
| Stop a service from running if it is currently running. |
| |
| swapon_all <fstab> |
| Calls fs_mgr_swapon_all on the given fstab file. |
| |
| symlink <target> <path> |
| Create a symbolic link at <path> with the value <target> |
| |
| sysclktz <mins_west_of_gmt> |
| Set the system clock base (0 if system clock ticks in GMT) |
| |
| trigger <event> |
| Trigger an event. Used to queue an action from another |
| action. |
| |
| umount <path> |
| Unmount the filesystem mounted at that path. |
| |
| verity_load_state |
| Internal implementation detail used to load dm-verity state. |
| |
| verity_update_state <mount_point> |
| Internal implementation detail used to update dm-verity state and |
| set the partition.<mount_point>.verified properties used by adb remount |
| because fs_mgr can't set them directly itself. |
| |
| wait <path> [ <timeout> ] |
| Poll for the existence of the given file and return when found, |
| or the timeout has been reached. If timeout is not specified it |
| currently defaults to five seconds. |
| |
| write <path> <content> |
| Open the file at <path> and write a string to it with write(2). |
| If the file does not exist, it will be created. If it does exist, |
| it will be truncated. Properties are expanded within <content>. |
| |
| |
| Imports |
| ------- |
| The import keyword is not a command, but rather its own section and is |
| handled immediately after the .rc file that contains it has finished |
| being parsed. It takes the below form: |
| |
| import <path> |
| Parse an init config file, extending the current configuration. |
| If <path> is a directory, each file in the directory is parsed as |
| a config file. It is not recursive, nested directories will |
| not be parsed. |
| |
| There are only two times where the init executable imports .rc files, |
| 1) When it imports /init.rc during initial boot |
| 2) When it imports /{system,vendor,odm}/etc/init/ or .rc files at specified |
| paths during mount_all |
| |
| |
| Properties |
| ---------- |
| Init provides information about the services that it is responsible |
| for via the below properties. |
| |
| init.start |
| Time after boot in ns (via the CLOCK_BOOTTIME clock) at which the first |
| stage of init started. |
| |
| init.svc.<name> |
| State of a named service ("stopped", "stopping", "running", "restarting") |
| |
| init.svc.<name>.start |
| Time after boot in ns (via the CLOCK_BOOTTIME clock) that the service was |
| most recently started. |
| |
| |
| Bootcharting |
| ------------ |
| This version of init contains code to perform "bootcharting": generating log |
| files that can be later processed by the tools provided by www.bootchart.org. |
| |
| On the emulator, use the -bootchart <timeout> option to boot with bootcharting |
| activated for <timeout> seconds. |
| |
| On a device, create /data/bootchart/start with a command like the following: |
| |
| adb shell 'echo $TIMEOUT > /data/bootchart/start' |
| |
| Where the value of $TIMEOUT corresponds to the desired bootcharted period in |
| seconds. Bootcharting will stop after that many seconds have elapsed. |
| You can also stop the bootcharting at any moment by doing the following: |
| |
| adb shell 'echo 1 > /data/bootchart/stop' |
| |
| Note that /data/bootchart/stop is deleted automatically by init at the end of |
| the bootcharting. This is not the case with /data/bootchart/start, so don't |
| forget to delete it when you're done collecting data. |
| |
| The log files are written to /data/bootchart/. A script is provided to |
| retrieve them and create a bootchart.tgz file that can be used with the |
| bootchart command-line utility: |
| |
| sudo apt-get install pybootchartgui |
| # grab-bootchart.sh uses $ANDROID_SERIAL. |
| $ANDROID_BUILD_TOP/system/core/init/grab-bootchart.sh |
| |
| One thing to watch for is that the bootchart will show init as if it started |
| running at 0s. You'll have to look at dmesg to work out when the kernel |
| actually started init. |
| |
| |
| Comparing two bootcharts |
| ------------------------ |
| A handy script named compare-bootcharts.py can be used to compare the |
| start/end time of selected processes. The aforementioned grab-bootchart.sh |
| will leave a bootchart tarball named bootchart.tgz at /tmp/android-bootchart. |
| If two such barballs are preserved on the host machine under different |
| directories, the script can list the timestamps differences. For example: |
| |
| Usage: system/core/init/compare-bootcharts.py base_bootchart_dir |
| exp_bootchart_dir |
| |
| process: baseline experiment (delta) |
| - Unit is ms (a jiffy is 10 ms on the system) |
| ------------------------------------ |
| /init: 50 40 (-10) |
| /system/bin/surfaceflinger: 4320 4470 (+150) |
| /system/bin/bootanimation: 6980 6990 (+10) |
| zygote64: 10410 10640 (+230) |
| zygote: 10410 10640 (+230) |
| system_server: 15350 15150 (-200) |
| bootanimation ends at: 33790 31230 (-2560) |
| |
| |
| Systrace |
| -------- |
| Systrace [1] can be used for obtaining performance analysis reports during boot |
| time on userdebug or eng builds. |
| Here is an example of trace events of "wm" and "am" categories: |
| |
| $ANDROID_BUILD_TOP/external/chromium-trace/systrace.py wm am --boot |
| |
| This command will cause the device to reboot. After the device is rebooted and |
| the boot sequence has finished, the trace report is obtained from the device |
| and written as trace.html on the host by hitting Ctrl+C. |
| |
| LIMITATION |
| Recording trace events is started after persistent properties are loaded, so |
| the trace events that are emitted before that are not recorded. Several |
| services such as vold, surfaceflinger, and servicemanager are affected by this |
| limitation since they are started before persistent properties are loaded. |
| Zygote initialization and the processes that are forked from the zygote are not |
| affected. |
| |
| [1] http://developer.android.com/tools/help/systrace.html |
| |
| |
| Debugging init |
| -------------- |
| By default, programs executed by init will drop stdout and stderr into |
| /dev/null. To help with debugging, you can execute your program via the |
| Android program logwrapper. This will redirect stdout/stderr into the |
| Android logging system (accessed via logcat). |
| |
| For example |
| service akmd /system/bin/logwrapper /sbin/akmd |
| |
| For quicker turnaround when working on init itself, use: |
| |
| mm -j && |
| m ramdisk-nodeps && |
| m bootimage-nodeps && |
| adb reboot bootloader && |
| fastboot boot $ANDROID_PRODUCT_OUT/boot.img |
| |
| Alternatively, use the emulator: |
| |
| emulator -partition-size 1024 -verbose -show-kernel -no-window |