The Android Open Source Project | 4f6e8d7 | 2008-10-21 07:00:00 -0700 | [diff] [blame] | 1 | |
| 2 | Android Init Language |
| 3 | --------------------- |
| 4 | |
| 5 | The Android Init Language consists of four broad classes of statements, |
| 6 | which are Actions, Commands, Services, and Options. |
| 7 | |
| 8 | All of these are line-oriented, consisting of tokens separated by |
| 9 | whitespace. The c-style backslash escapes may be used to insert |
| 10 | whitespace into a token. Double quotes may also be used to prevent |
| 11 | whitespace from breaking text into multiple tokens. The backslash, |
| 12 | when it is the last character on a line, may be used for line-folding. |
| 13 | |
| 14 | Lines which start with a # (leading whitespace allowed) are comments. |
| 15 | |
| 16 | Actions and Services implicitly declare a new section. All commands |
| 17 | or options belong to the section most recently declared. Commands |
| 18 | or options before the first section are ignored. |
| 19 | |
| 20 | Actions and Services have unique names. If a second Action or Service |
| 21 | is declared with the same name as an existing one, it is ignored as |
| 22 | an error. (??? should we override instead) |
| 23 | |
| 24 | |
| 25 | Actions |
| 26 | ------- |
| 27 | Actions are named sequences of commands. Actions have a trigger which |
| 28 | is used to determine when the action should occur. When an event |
| 29 | occurs which matches an action's trigger, that action is added to |
| 30 | the tail of a to-be-executed queue (unless it is already on the |
| 31 | queue). |
| 32 | |
| 33 | Each action in the queue is dequeued in sequence and each command in |
| 34 | that action is executed in sequence. Init handles other activities |
| 35 | (device creation/destruction, property setting, process restarting) |
| 36 | "between" the execution of the commands in activities. |
| 37 | |
| 38 | Actions take the form of: |
| 39 | |
| 40 | on <trigger> |
| 41 | <command> |
| 42 | <command> |
| 43 | <command> |
| 44 | |
| 45 | |
| 46 | Services |
| 47 | -------- |
| 48 | Services are programs which init launches and (optionally) restarts |
| 49 | when they exit. Services take the form of: |
| 50 | |
| 51 | service <name> <pathname> [ <argument> ]* |
| 52 | <option> |
| 53 | <option> |
| 54 | ... |
| 55 | |
| 56 | |
| 57 | Options |
| 58 | ------- |
| 59 | Options are modifiers to services. They affect how and when init |
| 60 | runs the service. |
| 61 | |
| 62 | critical |
| 63 | This is a device-critical service. If it exits more than four times in |
| 64 | four minutes, the device will reboot into recovery mode. |
| 65 | |
| 66 | disabled |
| 67 | This service will not automatically start with its class. |
| 68 | It must be explicitly started by name. |
| 69 | |
| 70 | setenv <name> <value> |
| 71 | Set the environment variable <name> to <value> in the launched process. |
| 72 | |
Stephen Smalley | 8348d27 | 2013-05-13 12:37:04 -0400 | [diff] [blame] | 73 | socket <name> <type> <perm> [ <user> [ <group> [ <context> ] ] ] |
The Android Open Source Project | 4f6e8d7 | 2008-10-21 07:00:00 -0700 | [diff] [blame] | 74 | Create a unix domain socket named /dev/socket/<name> and pass |
Mike Lockwood | 912ff85 | 2010-10-01 08:20:36 -0400 | [diff] [blame] | 75 | its fd to the launched process. <type> must be "dgram", "stream" or "seqpacket". |
The Android Open Source Project | 4f6e8d7 | 2008-10-21 07:00:00 -0700 | [diff] [blame] | 76 | User and group default to 0. |
Stephen Smalley | 8348d27 | 2013-05-13 12:37:04 -0400 | [diff] [blame] | 77 | Context is the SELinux security context for the socket. |
| 78 | It defaults to the service security context, as specified by seclabel or |
| 79 | computed based on the service executable file security context. |
The Android Open Source Project | 4f6e8d7 | 2008-10-21 07:00:00 -0700 | [diff] [blame] | 80 | |
| 81 | user <username> |
| 82 | Change to username before exec'ing this service. |
| 83 | Currently defaults to root. (??? probably should default to nobody) |
| 84 | Currently, if your process requires linux capabilities then you cannot use |
| 85 | this command. You must instead request the capabilities in-process while |
| 86 | still root, and then drop to your desired uid. |
| 87 | |
| 88 | group <groupname> [ <groupname> ]* |
| 89 | Change to groupname before exec'ing this service. Additional |
| 90 | groupnames beyond the (required) first one are used to set the |
| 91 | supplemental groups of the process (via setgroups()). |
| 92 | Currently defaults to root. (??? probably should default to nobody) |
| 93 | |
Stephen Smalley | 3fb6110 | 2012-11-02 15:22:34 -0400 | [diff] [blame] | 94 | seclabel <securitycontext> |
| 95 | Change to securitycontext before exec'ing this service. |
| 96 | Primarily for use by services run from the rootfs, e.g. ueventd, adbd. |
| 97 | Services on the system partition can instead use policy-defined transitions |
| 98 | based on their file security context. |
| 99 | If not specified and no transition is defined in policy, defaults to the init context. |
| 100 | |
The Android Open Source Project | 4f6e8d7 | 2008-10-21 07:00:00 -0700 | [diff] [blame] | 101 | oneshot |
| 102 | Do not restart the service when it exits. |
| 103 | |
| 104 | class <name> |
| 105 | Specify a class name for the service. All services in a |
| 106 | named class may be started or stopped together. A service |
| 107 | is in the class "default" if one is not specified via the |
| 108 | class option. |
| 109 | |
| 110 | onrestart |
| 111 | Execute a Command (see below) when service restarts. |
| 112 | |
Elliott Hughes | 841b263 | 2015-02-12 14:28:54 -0800 | [diff] [blame^] | 113 | |
The Android Open Source Project | 4f6e8d7 | 2008-10-21 07:00:00 -0700 | [diff] [blame] | 114 | Triggers |
| 115 | -------- |
| 116 | Triggers are strings which can be used to match certain kinds |
| 117 | of events and used to cause an action to occur. |
| 118 | |
| 119 | boot |
| 120 | This is the first trigger that will occur when init starts |
| 121 | (after /init.conf is loaded) |
| 122 | |
| 123 | <name>=<value> |
| 124 | Triggers of this form occur when the property <name> is set |
| 125 | to the specific value <value>. |
| 126 | |
Elliott Hughes | d3e37d1 | 2015-02-02 16:43:32 -0800 | [diff] [blame] | 127 | One can also test multiple properties to execute a group |
Badhri Jagan Sridharan | 0b41512 | 2014-10-10 23:19:06 -0700 | [diff] [blame] | 128 | of commands. For example: |
| 129 | |
| 130 | on property:test.a=1 && property:test.b=1 |
| 131 | setprop test.c 1 |
| 132 | |
| 133 | The above stub sets test.c to 1 only when |
| 134 | both test.a=1 and test.b=1 |
| 135 | |
Elliott Hughes | 841b263 | 2015-02-12 14:28:54 -0800 | [diff] [blame^] | 136 | |
The Android Open Source Project | 4f6e8d7 | 2008-10-21 07:00:00 -0700 | [diff] [blame] | 137 | Commands |
| 138 | -------- |
| 139 | |
| 140 | exec <path> [ <argument> ]* |
San Mehat | 429721c | 2014-09-23 07:48:47 -0700 | [diff] [blame] | 141 | This command is not implemented. |
| 142 | |
| 143 | execonce <path> [ <argument> ]* |
The Android Open Source Project | 4f6e8d7 | 2008-10-21 07:00:00 -0700 | [diff] [blame] | 144 | Fork and execute a program (<path>). This will block until |
San Mehat | 429721c | 2014-09-23 07:48:47 -0700 | [diff] [blame] | 145 | the program completes execution. This command can be run at most |
| 146 | once during init's lifetime. Subsequent invocations are ignored. |
| 147 | It is best to avoid exec as unlike the builtin commands, it runs |
| 148 | the risk of getting init "stuck". |
The Android Open Source Project | 4f6e8d7 | 2008-10-21 07:00:00 -0700 | [diff] [blame] | 149 | |
| 150 | export <name> <value> |
| 151 | Set the environment variable <name> equal to <value> in the |
| 152 | global environment (which will be inherited by all processes |
| 153 | started after this command is executed) |
| 154 | |
| 155 | ifup <interface> |
| 156 | Bring the network interface <interface> online. |
| 157 | |
| 158 | import <filename> |
| 159 | Parse an init config file, extending the current configuration. |
| 160 | |
| 161 | hostname <name> |
| 162 | Set the host name. |
| 163 | |
Jay Freeman (saurik) | e7cb137 | 2008-11-17 06:41:10 +0000 | [diff] [blame] | 164 | chdir <directory> |
| 165 | Change working directory. |
| 166 | |
The Android Open Source Project | 4f6e8d7 | 2008-10-21 07:00:00 -0700 | [diff] [blame] | 167 | chmod <octal-mode> <path> |
| 168 | Change file access permissions. |
| 169 | |
| 170 | chown <owner> <group> <path> |
| 171 | Change file owner and group. |
| 172 | |
Jay Freeman (saurik) | e7cb137 | 2008-11-17 06:41:10 +0000 | [diff] [blame] | 173 | chroot <directory> |
| 174 | Change process root directory. |
| 175 | |
The Android Open Source Project | 4f6e8d7 | 2008-10-21 07:00:00 -0700 | [diff] [blame] | 176 | class_start <serviceclass> |
| 177 | Start all services of the specified class if they are |
| 178 | not already running. |
| 179 | |
| 180 | class_stop <serviceclass> |
| 181 | Stop all services of the specified class if they are |
| 182 | currently running. |
| 183 | |
| 184 | domainname <name> |
| 185 | Set the domain name. |
| 186 | |
JP Abgrall | 3beec7e | 2014-05-02 21:14:29 -0700 | [diff] [blame] | 187 | enable <servicename> |
| 188 | Turns a disabled service into an enabled one as if the service did not |
| 189 | specify disabled. |
| 190 | If the service is supposed to be running, it will be started now. |
| 191 | Typically used when the bootloader sets a variable that indicates a specific |
| 192 | service should be started when needed. E.g. |
| 193 | on property:ro.boot.myfancyhardware=1 |
| 194 | enable my_fancy_service_for_my_fancy_hardware |
| 195 | |
The Android Open Source Project | 4f6e8d7 | 2008-10-21 07:00:00 -0700 | [diff] [blame] | 196 | insmod <path> |
| 197 | Install the module at <path> |
| 198 | |
Elliott Hughes | f682b47 | 2015-02-06 12:19:48 -0800 | [diff] [blame] | 199 | loglevel <level> |
| 200 | Sets the kernel log level to level. Properties are expanded within <level>. |
| 201 | |
The Android Open Source Project | 4f6e8d7 | 2008-10-21 07:00:00 -0700 | [diff] [blame] | 202 | mkdir <path> [mode] [owner] [group] |
| 203 | Create a directory at <path>, optionally with the given mode, owner, and |
| 204 | group. If not provided, the directory is created with permissions 755 and |
| 205 | owned by the root user and root group. |
| 206 | |
| 207 | mount <type> <device> <dir> [ <mountoption> ]* |
| 208 | Attempt to mount the named device at the directory <dir> |
| 209 | <device> may be of the form mtd@name to specify a mtd block |
| 210 | device by name. |
| 211 | <mountoption>s include "ro", "rw", "remount", "noatime", ... |
| 212 | |
Stephen Smalley | 726e8f7 | 2013-10-09 16:02:09 -0400 | [diff] [blame] | 213 | restorecon <path> [ <path> ]* |
Stephen Smalley | 3fb6110 | 2012-11-02 15:22:34 -0400 | [diff] [blame] | 214 | Restore the file named by <path> to the security context specified |
| 215 | in the file_contexts configuration. |
| 216 | Not required for directories created by the init.rc as these are |
| 217 | automatically labeled correctly by init. |
| 218 | |
Stephen Smalley | 726e8f7 | 2013-10-09 16:02:09 -0400 | [diff] [blame] | 219 | restorecon_recursive <path> [ <path> ]* |
| 220 | Recursively restore the directory tree named by <path> to the |
| 221 | security contexts specified in the file_contexts configuration. |
Stephen Smalley | 726e8f7 | 2013-10-09 16:02:09 -0400 | [diff] [blame] | 222 | |
Stephen Smalley | 3fb6110 | 2012-11-02 15:22:34 -0400 | [diff] [blame] | 223 | setcon <securitycontext> |
| 224 | Set the current process security context to the specified string. |
| 225 | This is typically only used from early-init to set the init context |
| 226 | before any other process is started. |
| 227 | |
| 228 | setenforce 0|1 |
| 229 | Set the SELinux system-wide enforcing status. |
| 230 | 0 is permissive (i.e. log but do not deny), 1 is enforcing. |
| 231 | |
The Android Open Source Project | 4f6e8d7 | 2008-10-21 07:00:00 -0700 | [diff] [blame] | 232 | setkey |
| 233 | TBD |
| 234 | |
| 235 | setprop <name> <value> |
Elliott Hughes | f682b47 | 2015-02-06 12:19:48 -0800 | [diff] [blame] | 236 | Set system property <name> to <value>. Properties are expanded |
| 237 | within <value>. |
The Android Open Source Project | 4f6e8d7 | 2008-10-21 07:00:00 -0700 | [diff] [blame] | 238 | |
| 239 | setrlimit <resource> <cur> <max> |
| 240 | Set the rlimit for a resource. |
| 241 | |
Stephen Smalley | 0e23fee | 2012-11-28 13:52:12 -0500 | [diff] [blame] | 242 | setsebool <name> <value> |
Stephen Smalley | 3fb6110 | 2012-11-02 15:22:34 -0400 | [diff] [blame] | 243 | Set SELinux boolean <name> to <value>. |
| 244 | <value> may be 1|true|on or 0|false|off |
| 245 | |
The Android Open Source Project | 4f6e8d7 | 2008-10-21 07:00:00 -0700 | [diff] [blame] | 246 | start <service> |
| 247 | Start a service running if it is not already running. |
| 248 | |
| 249 | stop <service> |
| 250 | Stop a service from running if it is currently running. |
| 251 | |
| 252 | symlink <target> <path> |
| 253 | Create a symbolic link at <path> with the value <target> |
| 254 | |
The Android Open Source Project | 35237d1 | 2008-12-17 18:08:08 -0800 | [diff] [blame] | 255 | sysclktz <mins_west_of_gmt> |
| 256 | Set the system clock base (0 if system clock ticks in GMT) |
| 257 | |
The Android Open Source Project | 4f6e8d7 | 2008-10-21 07:00:00 -0700 | [diff] [blame] | 258 | trigger <event> |
| 259 | Trigger an event. Used to queue an action from another |
| 260 | action. |
| 261 | |
Patrick McCormick | 96d0a4d | 2011-02-04 10:51:39 -0800 | [diff] [blame] | 262 | wait <path> [ <timeout> ] |
| 263 | Poll for the existence of the given file and return when found, |
| 264 | or the timeout has been reached. If timeout is not specified it |
| 265 | currently defaults to five seconds. |
| 266 | |
Elliott Hughes | f682b47 | 2015-02-06 12:19:48 -0800 | [diff] [blame] | 267 | write <path> <content> |
| 268 | Open the file at <path> and write a string to it with write(2). |
| 269 | If the file does not exist, it will be created. If it does exist, |
| 270 | it will be truncated. Properties are expanded within <content>. |
The Android Open Source Project | 4f6e8d7 | 2008-10-21 07:00:00 -0700 | [diff] [blame] | 271 | |
| 272 | |
| 273 | Properties |
| 274 | ---------- |
| 275 | Init updates some system properties to provide some insight into |
| 276 | what it's doing: |
| 277 | |
| 278 | init.action |
| 279 | Equal to the name of the action currently being executed or "" if none |
| 280 | |
| 281 | init.command |
| 282 | Equal to the command being executed or "" if none. |
| 283 | |
| 284 | init.svc.<name> |
| 285 | State of a named service ("stopped", "running", "restarting") |
| 286 | |
| 287 | |
Elliott Hughes | 841b263 | 2015-02-12 14:28:54 -0800 | [diff] [blame^] | 288 | Bootcharting |
| 289 | ------------ |
The Android Open Source Project | 4f6e8d7 | 2008-10-21 07:00:00 -0700 | [diff] [blame] | 290 | |
Elliott Hughes | 841b263 | 2015-02-12 14:28:54 -0800 | [diff] [blame^] | 291 | This version of init contains code to perform "bootcharting": generating log |
| 292 | files that can be later processed by the tools provided by www.bootchart.org. |
The Android Open Source Project | 4f6e8d7 | 2008-10-21 07:00:00 -0700 | [diff] [blame] | 293 | |
Elliott Hughes | 841b263 | 2015-02-12 14:28:54 -0800 | [diff] [blame^] | 294 | On the emulator, use the new -bootchart <timeout> option to boot with |
| 295 | bootcharting activated for <timeout> seconds. |
The Android Open Source Project | 4f6e8d7 | 2008-10-21 07:00:00 -0700 | [diff] [blame] | 296 | |
Elliott Hughes | 841b263 | 2015-02-12 14:28:54 -0800 | [diff] [blame^] | 297 | On a device, create /data/bootchart/start with a command like the following: |
The Android Open Source Project | 4f6e8d7 | 2008-10-21 07:00:00 -0700 | [diff] [blame] | 298 | |
Elliott Hughes | 841b263 | 2015-02-12 14:28:54 -0800 | [diff] [blame^] | 299 | adb shell 'echo $TIMEOUT > /data/bootchart/start' |
The Android Open Source Project | 4f6e8d7 | 2008-10-21 07:00:00 -0700 | [diff] [blame] | 300 | |
Elliott Hughes | 841b263 | 2015-02-12 14:28:54 -0800 | [diff] [blame^] | 301 | Where the value of $TIMEOUT corresponds to the desired bootcharted period in |
| 302 | seconds. Bootcharting will stop after that many seconds have elapsed. |
| 303 | You can also stop the bootcharting at any moment by doing the following: |
The Android Open Source Project | 4f6e8d7 | 2008-10-21 07:00:00 -0700 | [diff] [blame] | 304 | |
Elliott Hughes | 841b263 | 2015-02-12 14:28:54 -0800 | [diff] [blame^] | 305 | adb shell 'echo 1 > /data/bootchart/stop' |
The Android Open Source Project | 4f6e8d7 | 2008-10-21 07:00:00 -0700 | [diff] [blame] | 306 | |
Elliott Hughes | 841b263 | 2015-02-12 14:28:54 -0800 | [diff] [blame^] | 307 | Note that /data/bootchart/stop is deleted automatically by init at the end of |
| 308 | the bootcharting. This is not the case with /data/bootchart/start, so don't |
| 309 | forget to delete it when you're done collecting data. |
The Android Open Source Project | 4f6e8d7 | 2008-10-21 07:00:00 -0700 | [diff] [blame] | 310 | |
Elliott Hughes | 841b263 | 2015-02-12 14:28:54 -0800 | [diff] [blame^] | 311 | The log files are written to /data/bootchart/. A script is provided to |
| 312 | retrieve them and create a bootchart.tgz file that can be used with the |
| 313 | bootchart command-line utility: |
The Android Open Source Project | 4f6e8d7 | 2008-10-21 07:00:00 -0700 | [diff] [blame] | 314 | |
Elliott Hughes | 841b263 | 2015-02-12 14:28:54 -0800 | [diff] [blame^] | 315 | sudo apt-get install pybootchartgui |
| 316 | $ANDROID_BUILD_TOP/system/core/init/grab-bootchart.sh |
| 317 | bootchart ./bootchart.tgz |
| 318 | gnome-open bootchart.png |
The Android Open Source Project | 4f6e8d7 | 2008-10-21 07:00:00 -0700 | [diff] [blame] | 319 | |
The Android Open Source Project | 4f6e8d7 | 2008-10-21 07:00:00 -0700 | [diff] [blame] | 320 | |
Elliott Hughes | 841b263 | 2015-02-12 14:28:54 -0800 | [diff] [blame^] | 321 | Debugging init |
| 322 | -------------- |
The Android Open Source Project | 4f6e8d7 | 2008-10-21 07:00:00 -0700 | [diff] [blame] | 323 | By default, programs executed by init will drop stdout and stderr into |
| 324 | /dev/null. To help with debugging, you can execute your program via the |
Elliott Hughes | f682b47 | 2015-02-06 12:19:48 -0800 | [diff] [blame] | 325 | Android program logwrapper. This will redirect stdout/stderr into the |
The Android Open Source Project | 4f6e8d7 | 2008-10-21 07:00:00 -0700 | [diff] [blame] | 326 | Android logging system (accessed via logcat). |
| 327 | |
| 328 | For example |
| 329 | service akmd /system/bin/logwrapper /sbin/akmd |
Elliott Hughes | f682b47 | 2015-02-06 12:19:48 -0800 | [diff] [blame] | 330 | |
| 331 | For quicker turnaround when working on init itself, use: |
| 332 | |
Elliott Hughes | 841b263 | 2015-02-12 14:28:54 -0800 | [diff] [blame^] | 333 | mm -j |
Elliott Hughes | f682b47 | 2015-02-06 12:19:48 -0800 | [diff] [blame] | 334 | m ramdisk-nodeps |
| 335 | m bootimage-nodeps |
| 336 | adb reboot bootloader |
| 337 | fastboot boot $ANDROID_PRODUCT_OUT/boot.img |
| 338 | |
| 339 | Alternatively, use the emulator: |
| 340 | |
| 341 | emulator -partition-size 1024 -verbose -show-kernel -no-window |
| 342 | |
| 343 | You might want to call klog_set_level(6) after the klog_init() call |
| 344 | so you see the kernel logging in dmesg (or the emulator output). |