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 | |
| 113 | Triggers |
| 114 | -------- |
| 115 | Triggers are strings which can be used to match certain kinds |
| 116 | of events and used to cause an action to occur. |
| 117 | |
| 118 | boot |
| 119 | This is the first trigger that will occur when init starts |
| 120 | (after /init.conf is loaded) |
| 121 | |
| 122 | <name>=<value> |
| 123 | Triggers of this form occur when the property <name> is set |
| 124 | to the specific value <value>. |
| 125 | |
Elliott Hughes | d3e37d1 | 2015-02-02 16:43:32 -0800 | [diff] [blame] | 126 | One can also test multiple properties to execute a group |
Badhri Jagan Sridharan | 0b41512 | 2014-10-10 23:19:06 -0700 | [diff] [blame] | 127 | of commands. For example: |
| 128 | |
| 129 | on property:test.a=1 && property:test.b=1 |
| 130 | setprop test.c 1 |
| 131 | |
| 132 | The above stub sets test.c to 1 only when |
| 133 | both test.a=1 and test.b=1 |
| 134 | |
The Android Open Source Project | 4f6e8d7 | 2008-10-21 07:00:00 -0700 | [diff] [blame] | 135 | Commands |
| 136 | -------- |
| 137 | |
| 138 | exec <path> [ <argument> ]* |
San Mehat | 429721c | 2014-09-23 07:48:47 -0700 | [diff] [blame] | 139 | This command is not implemented. |
| 140 | |
| 141 | execonce <path> [ <argument> ]* |
The Android Open Source Project | 4f6e8d7 | 2008-10-21 07:00:00 -0700 | [diff] [blame] | 142 | Fork and execute a program (<path>). This will block until |
San Mehat | 429721c | 2014-09-23 07:48:47 -0700 | [diff] [blame] | 143 | the program completes execution. This command can be run at most |
| 144 | once during init's lifetime. Subsequent invocations are ignored. |
| 145 | It is best to avoid exec as unlike the builtin commands, it runs |
| 146 | the risk of getting init "stuck". |
The Android Open Source Project | 4f6e8d7 | 2008-10-21 07:00:00 -0700 | [diff] [blame] | 147 | |
| 148 | export <name> <value> |
| 149 | Set the environment variable <name> equal to <value> in the |
| 150 | global environment (which will be inherited by all processes |
| 151 | started after this command is executed) |
| 152 | |
| 153 | ifup <interface> |
| 154 | Bring the network interface <interface> online. |
| 155 | |
| 156 | import <filename> |
| 157 | Parse an init config file, extending the current configuration. |
| 158 | |
| 159 | hostname <name> |
| 160 | Set the host name. |
| 161 | |
Jay Freeman (saurik) | e7cb137 | 2008-11-17 06:41:10 +0000 | [diff] [blame] | 162 | chdir <directory> |
| 163 | Change working directory. |
| 164 | |
The Android Open Source Project | 4f6e8d7 | 2008-10-21 07:00:00 -0700 | [diff] [blame] | 165 | chmod <octal-mode> <path> |
| 166 | Change file access permissions. |
| 167 | |
| 168 | chown <owner> <group> <path> |
| 169 | Change file owner and group. |
| 170 | |
Jay Freeman (saurik) | e7cb137 | 2008-11-17 06:41:10 +0000 | [diff] [blame] | 171 | chroot <directory> |
| 172 | Change process root directory. |
| 173 | |
The Android Open Source Project | 4f6e8d7 | 2008-10-21 07:00:00 -0700 | [diff] [blame] | 174 | class_start <serviceclass> |
| 175 | Start all services of the specified class if they are |
| 176 | not already running. |
| 177 | |
| 178 | class_stop <serviceclass> |
| 179 | Stop all services of the specified class if they are |
| 180 | currently running. |
| 181 | |
| 182 | domainname <name> |
| 183 | Set the domain name. |
| 184 | |
JP Abgrall | 3beec7e | 2014-05-02 21:14:29 -0700 | [diff] [blame] | 185 | enable <servicename> |
| 186 | Turns a disabled service into an enabled one as if the service did not |
| 187 | specify disabled. |
| 188 | If the service is supposed to be running, it will be started now. |
| 189 | Typically used when the bootloader sets a variable that indicates a specific |
| 190 | service should be started when needed. E.g. |
| 191 | on property:ro.boot.myfancyhardware=1 |
| 192 | enable my_fancy_service_for_my_fancy_hardware |
| 193 | |
| 194 | |
The Android Open Source Project | 4f6e8d7 | 2008-10-21 07:00:00 -0700 | [diff] [blame] | 195 | insmod <path> |
| 196 | Install the module at <path> |
| 197 | |
| 198 | mkdir <path> [mode] [owner] [group] |
| 199 | Create a directory at <path>, optionally with the given mode, owner, and |
| 200 | group. If not provided, the directory is created with permissions 755 and |
| 201 | owned by the root user and root group. |
| 202 | |
| 203 | mount <type> <device> <dir> [ <mountoption> ]* |
| 204 | Attempt to mount the named device at the directory <dir> |
| 205 | <device> may be of the form mtd@name to specify a mtd block |
| 206 | device by name. |
| 207 | <mountoption>s include "ro", "rw", "remount", "noatime", ... |
| 208 | |
Stephen Smalley | 726e8f7 | 2013-10-09 16:02:09 -0400 | [diff] [blame] | 209 | restorecon <path> [ <path> ]* |
Stephen Smalley | 3fb6110 | 2012-11-02 15:22:34 -0400 | [diff] [blame] | 210 | Restore the file named by <path> to the security context specified |
| 211 | in the file_contexts configuration. |
| 212 | Not required for directories created by the init.rc as these are |
| 213 | automatically labeled correctly by init. |
| 214 | |
Stephen Smalley | 726e8f7 | 2013-10-09 16:02:09 -0400 | [diff] [blame] | 215 | restorecon_recursive <path> [ <path> ]* |
| 216 | Recursively restore the directory tree named by <path> to the |
| 217 | security contexts specified in the file_contexts configuration. |
Stephen Smalley | 726e8f7 | 2013-10-09 16:02:09 -0400 | [diff] [blame] | 218 | |
Stephen Smalley | 3fb6110 | 2012-11-02 15:22:34 -0400 | [diff] [blame] | 219 | setcon <securitycontext> |
| 220 | Set the current process security context to the specified string. |
| 221 | This is typically only used from early-init to set the init context |
| 222 | before any other process is started. |
| 223 | |
| 224 | setenforce 0|1 |
| 225 | Set the SELinux system-wide enforcing status. |
| 226 | 0 is permissive (i.e. log but do not deny), 1 is enforcing. |
| 227 | |
The Android Open Source Project | 4f6e8d7 | 2008-10-21 07:00:00 -0700 | [diff] [blame] | 228 | setkey |
| 229 | TBD |
| 230 | |
| 231 | setprop <name> <value> |
| 232 | Set system property <name> to <value>. |
| 233 | |
| 234 | setrlimit <resource> <cur> <max> |
| 235 | Set the rlimit for a resource. |
| 236 | |
Stephen Smalley | 0e23fee | 2012-11-28 13:52:12 -0500 | [diff] [blame] | 237 | setsebool <name> <value> |
Stephen Smalley | 3fb6110 | 2012-11-02 15:22:34 -0400 | [diff] [blame] | 238 | Set SELinux boolean <name> to <value>. |
| 239 | <value> may be 1|true|on or 0|false|off |
| 240 | |
The Android Open Source Project | 4f6e8d7 | 2008-10-21 07:00:00 -0700 | [diff] [blame] | 241 | start <service> |
| 242 | Start a service running if it is not already running. |
| 243 | |
| 244 | stop <service> |
| 245 | Stop a service from running if it is currently running. |
| 246 | |
| 247 | symlink <target> <path> |
| 248 | Create a symbolic link at <path> with the value <target> |
| 249 | |
The Android Open Source Project | 35237d1 | 2008-12-17 18:08:08 -0800 | [diff] [blame] | 250 | sysclktz <mins_west_of_gmt> |
| 251 | Set the system clock base (0 if system clock ticks in GMT) |
| 252 | |
The Android Open Source Project | 4f6e8d7 | 2008-10-21 07:00:00 -0700 | [diff] [blame] | 253 | trigger <event> |
| 254 | Trigger an event. Used to queue an action from another |
| 255 | action. |
| 256 | |
Patrick McCormick | 96d0a4d | 2011-02-04 10:51:39 -0800 | [diff] [blame] | 257 | wait <path> [ <timeout> ] |
| 258 | Poll for the existence of the given file and return when found, |
| 259 | or the timeout has been reached. If timeout is not specified it |
| 260 | currently defaults to five seconds. |
| 261 | |
Elliott Hughes | afc08ce | 2014-07-25 10:39:41 -0700 | [diff] [blame] | 262 | write <path> <string> |
| 263 | Open the file at <path> and write a string to it with write(2) |
| 264 | without appending. |
The Android Open Source Project | 4f6e8d7 | 2008-10-21 07:00:00 -0700 | [diff] [blame] | 265 | |
| 266 | |
| 267 | Properties |
| 268 | ---------- |
| 269 | Init updates some system properties to provide some insight into |
| 270 | what it's doing: |
| 271 | |
| 272 | init.action |
| 273 | Equal to the name of the action currently being executed or "" if none |
| 274 | |
| 275 | init.command |
| 276 | Equal to the command being executed or "" if none. |
| 277 | |
| 278 | init.svc.<name> |
| 279 | State of a named service ("stopped", "running", "restarting") |
| 280 | |
| 281 | |
| 282 | Example init.conf |
| 283 | ----------------- |
| 284 | |
| 285 | # not complete -- just providing some examples of usage |
| 286 | # |
| 287 | on boot |
| 288 | export PATH /sbin:/system/sbin:/system/bin |
| 289 | export LD_LIBRARY_PATH /system/lib |
| 290 | |
| 291 | mkdir /dev |
| 292 | mkdir /proc |
| 293 | mkdir /sys |
| 294 | |
| 295 | mount tmpfs tmpfs /dev |
| 296 | mkdir /dev/pts |
| 297 | mkdir /dev/socket |
| 298 | mount devpts devpts /dev/pts |
| 299 | mount proc proc /proc |
| 300 | mount sysfs sysfs /sys |
| 301 | |
| 302 | write /proc/cpu/alignment 4 |
| 303 | |
| 304 | ifup lo |
| 305 | |
| 306 | hostname localhost |
| 307 | domainname localhost |
| 308 | |
| 309 | mount yaffs2 mtd@system /system |
| 310 | mount yaffs2 mtd@userdata /data |
| 311 | |
| 312 | import /system/etc/init.conf |
| 313 | |
| 314 | class_start default |
| 315 | |
| 316 | service adbd /sbin/adbd |
| 317 | user adb |
| 318 | group adb |
| 319 | |
| 320 | service usbd /system/bin/usbd -r |
| 321 | user usbd |
| 322 | group usbd |
| 323 | socket usbd 666 |
| 324 | |
| 325 | service zygote /system/bin/app_process -Xzygote /system/bin --zygote |
| 326 | socket zygote 666 |
| 327 | |
| 328 | service runtime /system/bin/runtime |
| 329 | user system |
| 330 | group system |
| 331 | |
The Android Open Source Project | 4f6e8d7 | 2008-10-21 07:00:00 -0700 | [diff] [blame] | 332 | service akmd /sbin/akmd |
| 333 | disabled |
| 334 | user akmd |
| 335 | group akmd |
| 336 | |
| 337 | Debugging notes |
| 338 | --------------- |
| 339 | By default, programs executed by init will drop stdout and stderr into |
| 340 | /dev/null. To help with debugging, you can execute your program via the |
| 341 | Andoird program logwrapper. This will redirect stdout/stderr into the |
| 342 | Android logging system (accessed via logcat). |
| 343 | |
| 344 | For example |
| 345 | service akmd /system/bin/logwrapper /sbin/akmd |