【Android7.1.2源码解析系列】android中init.rc文件的语法

译自：system/core/init/readme.txt

译文

Android初始化语言
===================


Android 初始化语言由动作(Action)、命令(Command)、服务(Service)、条件(Option)四类状态组成。


这四类状态都是行定向的，由空格分开的记号(token)组成。c风格的斜杠可能被用来向记号(token)里插入空格。双引号可以被用来避免空格把文字分割为不同的片段。最后一行的斜杠可能被用来进行行连接。


以#开头的行是注释(允许在之前插入空格)。


动作(Actions)和服务(Services)明确地指出了一个新的片段。所有的命令(Command)或者条件(Option)将属于最新定义的模块。先于第一个片段的命令(Command)和条件(Option)将被忽略。


动作(Actions)和服务(Services)有唯一的名称。如果有第二个动作(Aciton)或者服务(Service)被定义为和一个已存在的动作(Action)或服务(Service)同样的名称，它将会作为一个错误来被忽略。(???我们是不是应该覆盖掉而不是忽略的)


动作(Actions)
=======
动作(Actions)是命令(Commands)的已命名的序列。动作(Action)有一个指明何时动作(Action)应该发生的触发器。当一个满足动作(Action)的触发器的事件发生时，该动作(Action)就被加入到一个需要执行的动作(action)列表的尾部(除非它已经存在于该队列)。


每一个队列当中的动作(action)从序列当中出列，并且每一个动作(action)中的命令(command)在序列当中被执行。init程序掌握了在命令(command)执行之间的其他动作（硬件设备的创建与销毁、属性设置、进程重启）。


动作(Action)的格式如下：


on <触发器(trigger)>
   
   
   






服务（Services）
========
服务(Service)是程序初始化进行或者退出时重新启动的方案。
服务(Service)的格式如下：


service []*
   
   
   ...






条件(Options)
=======
条件(Option)是服务(Service)的修饰者。他们影响着init程序怎样以及何时运行服务(service)。


严重的(critical)：
   这是一个硬件级的服务(service)。如果它在四分钟内退出了超过四次，设备将会重启到恢复模式(recovery mode)。


被停用的(disabled)：
   这个服务(service)不会自动的随它的类而开启。它必须明确的通过它的名称来开启。


setenv
   将启动过程中的名为的环境变量的值设置为。




socket [ [ [ ] ] ]
   创建一个名为/dev/socket/的unix属性的socket连接并且将它的文件描述符传递给登录的进程。必须是"dgram"、"stream"或"seqpacket"中的其中一个。
   user和group的值默认为0。
   context是selinux的安全上下文。
   该属性被默认设置为service的安全上下文，也可以被安全标签指明或者通过service的可执行文件的安全上下文来计算。
   


user
   在执行当前服务(service)之前把它的用户名更换为username。
   现在默认设置为root。(???可能应该默认设置为nobody)
   现在，如果你的进程需要linux的功能你就不能使用这个命令(command)。在你依然处于root状态时，你必须在进程当中申请这些能力，并且跳转到你期望的uid。


group [ ]*
   在执行当前服务(service)之前把它的用户组名更换为groupname。
   额外的第一个更多的用户组名被用于设置进程额外的用户组(通过setgroups()指明)。
   现在默认设置为root。(???可能应该默认设置为nobody)


seclabel
   在执行当前服务(service)之前把它的安装上下文设置为sercuritycontext。
   主要用于通过rootfs、ueventd以及adbd等等运行的服务(service)。
   系统分区当中的服务也可以使用通过他们的文件安全上下文定义的策略来过渡。
   如果既没有指明安全上下文，也没有通过策略进行定义，则默认设置为init进程的安全上下文。
  


onshot
   当该服务(service)退出时不要重启它。




class  
   为该服务(service)指明一个类名。在同一个类名当中的服务(service)可以被同时打开或者停止。未通过条件(option)指明类名的服务默认设置类名为"default"。




onrestart
   当服务(service)重启时执行一个命令(command)(查看后面的command部分)。






Triggers
========
   触发器(triggers)是可以被用来匹配明确种类的事件的字符串，并且用来造成一个动作(action)的发生。
   


boot
   这是init程序开启时(在 /init.conf 被加载后)会发生的第一个触发器(trigger)。




=
   这种形式的策略(trigger)在名为的属性的值被设置为指定的值的时候触发。




device-added-
device-removed-
   这些形式的触发器(triggers)会在一个设备节点被添加或移除的时候触发。




service-exited-
   这种形式的触发器(triggers)会在指明的服务(service)退出时触发。






Commands
========


exec [ ]*
   产生(fork)并且执行一个程序()。这个命令会在这个程序完整退出前锁住。
   最好是避免内置用户的命令(command)之外的exec命令，因为它会导致init程序运行在"卡死"的风险之下。(???也许这里需要有一个超时时间)




export
   将名为的环境变量在全局中设置为与名为的环境变量相同(所有在此命令(command)执行之后的进程都会继承该环境变量)。




ifup
   使得网络接口在线。




import
   粘贴一个init进程的配置文件，扩展当前的配置。




hostname
   设置主机名称。




chdir
   修改工作目录。




chmod
   改变文件入口权限。




chown
   改变文件的拥有者和所在的组。




chroot
   改变进程根目录。




class_start
   打开所有类名为serviceclass的类当中的未运行的服务(services)。




class_stop
   关闭所有类名为serviceclass的类当中的正在运行的服务(services)。




domainname
   设置属性名。




enable
   将一个关闭的服务(service)打开，就好像这个服务没有被关闭过。
   如果这个服务被期望运行，它就会在现在被开启。
   典型的使用是bootloader设置了一个变量来指明一个服务(service)应该在需要的时候被开启。例如当属性:ro.boot.myfancyhardware=1时打开my_fancy_service_for_my_fancy_hardware




insmod
   在目录下安装该模块




mkdir [mode] [owner] [group]
   创建一个目录，可以加入mode、owner和group选项。如果没有提供，目录会以755权限创建并且属于root用户和root用户组。




mount [ ]*
   尝试将为名称的设备挂载到目录上。
   可以以mtd@name的格式来指明一个名为name的mtd固定设备。
   s(挂载选项)包括"ro"、"rw"、"remount"、"noatime"...




readprops
   通过下的文本文件的内容来读取系统属性。




restorecon [ ]*
   把下的文件重新保存到通过文件上下文配置指明的安全上下文中。
   被init.rc创建的目录不需要，因为这些已经被init进程自动而正确的标记。




restorecon_recursive [ ]*
   把下的文件树递归的重新保存到通过文件上下文配置指明的安全上下文中。
   不要在导向shell可写或者app可写的目录下使用这个命令，例如/data/local/tmp,/data/data或者其他任何以此前缀的文件夹。




setcon
   将当前进程的安全上下文设置为指明的字符串。
   这个命令只是被典型的用于early-init中来在任何进程开启前设置init的上下文。




setenforce 0|1
   设置Selinux系统内外的强制开关状态。
   0代表允许(指的是对于selinux记录日志但是不阻止)，1代表强制开启。




setkey
   待定




setkeycode
   在系统的搜索模式到关键模式的map表中设置一个实体。




setprop
   将名为的系统属性的值设置为。




setrlimit
   设置一个资源的资源限制。




setsebool
   设置selinux的名为的布尔变量的值。
   可以是 1|true|on 或者是 0|false|off




start
   将一个未运行的服务(service)开启。




stop
   关闭一个正在运行的服务(service)。




symlink
   创建一个到的符号链接。




sysclktz
   设置系统时钟的基准(在格林尼治标准时间(gmt)下设置为0)。




trigger
   触发一个事件。用来把一个一个action进行编队。




wait [ ]
   调查所给出文件的存在性并且在找到或者超时的时候返回。如果timeout没有被指明，则按照现在的默认值5秒。




write
   打开目录的文件并且把一个字符串写入(非附加形式)。
   




Properties
==========
   init进程更新了一些系统属性来提供一些对于内部在做什么的观测方式。
   
init.action
   和当前正在执行的动作(action)的名称相同，如果没有，则是""。


init.command
   和当前正在执行的命令(command)的名称相同，如果没有，则是""。


init.svc.
   以为名的服务(service)的状态("stopped"、"runnning"、"restarting")。




init.conf的例子
===============


# not complete -- just providing some examples of usage
# 直译
# 不完整 -- 只是提供一些使用的例子


# 第一部分，action片段，在boot时，会依次执行下列的命令（从export PATH /sbin  到 class_start default）
on boot
   export PATH /sbin:/system/sbin:/system/bin
   export LD_LIBRARY_PATH /system/lib


   mkdir /dev
   mkdir /proc
   mkdir /sys


   mount tmpfs tmpfs /dev
   mkdir /dev/pts
   mkdir /dev/socket
   mount devpts devpts /dev/pts
   mount proc proc /proc
   mount sysfs sysfs /sys


   write /proc/cpu/alignment 4


   ifup lo


   hostname localhost
   domainname localhost


   mount yaffs2 mtd@system /system
   mount yaffs2 mtd@userdata /data


   import /system/etc/init.conf


   class_start default


# 第二部分，service， 定义了一个位于sbin/adbd的名为adbd的服务
service adbd /sbin/adbd
   user adb
   group adb


service usbd /system/bin/usbd -r
   user usbd
   group usbd
   socket usbd 666


service zygote /system/bin/app_process -Xzygote /system/bin --zygote
   socket zygote 666


service runtime /system/bin/runtime
   user system
   group system


on device-added-/dev/compass
   start akmd


on device-removed-/dev/compass
   stop akmd


service akmd /sbin/akmd
   disabled
   user akmd
   group akmd




调试记录
========
   默认情况下，由init进程执行的程序会将stdout和stderr输出到/dev/null。为了有助于调试，你可以执行你的明确的日志程序logwrapper。这会将stdout与stderr重定向到Android日志系统。(明确可达的logcat)


举个例子
   service akmd /system/bin/logwrapper /sbin/akmd

原文

Android Init Language
---------------------


The Android Init Language consists of four broad classes of statements,
which are Actions, Commands, Services, and Options.


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 or Service
is declared with the same name as an existing one, it is ignored as
an error.  (??? should we override instead)




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
   
   
   




Services
--------
Services are programs which init launches and (optionally) restarts
when they exit.  Services take the form of:


service [ ]*
   
   
   ...




Options
-------
Options are modifiers to services.  They affect how and when init
runs the service.


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
   Set the environment variable to in the launched process.


socket [ [ [ ] ] ]
   Create a unix domain socket named /dev/socket/ and pass
   its fd to the launched process.   must be "dgram", "stream" or "seqpacket".
   User and group default to 0.
   Context 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.


user
   Change to username before exec'ing this service.
   Currently defaults to root.  (??? probably should default to nobody)
   Currently, if your process requires linux capabilities then you cannot use
   this command. You must instead request the capabilities in-process while
   still root, and then drop to your desired uid.


group [ ]*
   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)


seclabel
  Change to securitycontext 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
   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.


Triggers
--------
   Triggers are strings which can be used to match certain kinds
   of events and used to cause an action to occur.


boot
   This is the first trigger that will occur when init starts
   (after /init.conf is loaded)


=
   Triggers of this form occur when the property is set
   to the specific value .


device-added-
device-removed-
   Triggers of these forms occur when a device node is added
   or removed.


service-exited-
   Triggers of this form occur when the specified service exits.




Commands
--------


exec [ ]*
   Fork and execute a program ().  This will block until
   the program completes execution.  It is best to avoid exec
   as unlike the builtin commands, it runs the risk of getting
   init "stuck". (??? maybe there should be a timeout?)


export
   Set the environment variable equal to in the
   global environment (which will be inherited by all processes
   started after this command is executed)


ifup
   Bring the network interface online.


import
   Parse an init config file, extending the current configuration.


hostname
   Set the host name.


chdir
   Change working directory.


chmod
   Change file access permissions.


chown
   Change file owner and group.


chroot
  Change process root directory.


class_start
   Start all services of the specified class if they are
   not already running.


class_stop
   Stop all services of the specified class if they are
   currently running.


domainname
   Set the domain name.


enable
   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




insmod
   Install the module at


mkdir [mode] [owner] [group]
   Create a directory at , 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.


mount [ ]*
   Attempt to mount the named device at the directory
    may be of the form mtd@name to specify a mtd block
   device by name.
   s include "ro", "rw", "remount", "noatime", ...


readprops
   Read and set system properties based on the contents of a text file
   at


restorecon [ ]*
   Restore the file named by 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 [ ]*
   Recursively restore the directory tree named by to the
   security contexts specified in the file_contexts configuration.
   Do NOT use this with paths leading to shell-writable or app-writable
   directories, e.g. /data/local/tmp, /data/data or any prefix thereof.


setcon
   Set the current process security context to the specified string.
   This is typically only used from early-init to set the init context
   before any other process is started.


setenforce 0|1
   Set the SELinux system-wide enforcing status.
   0 is permissive (i.e. log but do not deny), 1 is enforcing.


setkey
   TBD


setkeycode
   Set an entry into the kernel's scancode-to-keycode map.


setprop
   Set system property to .


setrlimit
   Set the rlimit for a resource.


setsebool
   Set SELinux boolean to .
    may be 1|true|on or 0|false|off


start
   Start a service running if it is not already running.


stop
   Stop a service from running if it is currently running.


symlink
   Create a symbolic link at with the value


sysclktz
   Set the system clock base (0 if system clock ticks in GMT)


trigger
   Trigger an event.  Used to queue an action from another
   action.


wait [ ]
  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
   Open the file at and write a string to it with write(2)
   without appending.




Properties
----------
Init updates some system properties to provide some insight into
what it's doing:


init.action 
   Equal to the name of the action currently being executed or "" if none


init.command
   Equal to the command being executed or "" if none.


init.svc.
   State of a named service ("stopped", "running", "restarting")




Example init.conf
-----------------


# not complete -- just providing some examples of usage
#
on boot
   export PATH /sbin:/system/sbin:/system/bin
   export LD_LIBRARY_PATH /system/lib


   mkdir /dev
   mkdir /proc
   mkdir /sys


   mount tmpfs tmpfs /dev
   mkdir /dev/pts
   mkdir /dev/socket
   mount devpts devpts /dev/pts
   mount proc proc /proc
   mount sysfs sysfs /sys


   write /proc/cpu/alignment 4


   ifup lo


   hostname localhost
   domainname localhost


   mount yaffs2 mtd@system /system
   mount yaffs2 mtd@userdata /data


   import /system/etc/init.conf


   class_start default


service adbd /sbin/adbd
   user adb
   group adb


service usbd /system/bin/usbd -r
   user usbd
   group usbd
   socket usbd 666


service zygote /system/bin/app_process -Xzygote /system/bin --zygote
   socket zygote 666


service runtime /system/bin/runtime
   user system
   group system


on device-added-/dev/compass
   start akmd


on device-removed-/dev/compass
   stop akmd


service akmd /sbin/akmd
   disabled
   user akmd
   group akmd


Debugging notes
---------------
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
Andoird program logwrapper. This will redirect stdout/stderr into the
Android logging system (accessed via logcat).


For example
service akmd /system/bin/logwrapper /sbin/akmd