openwrt3

1.3 Advanced configuration

Structure of the configuration files

The config files are divided into sections and options/values.

Every section has a type, but does not necessarily have a name. Every option has a name and a value and is assigned to the section it was written under.

该配置文件被分为几个章节，和选项/值。每一个章节都有其类型，但没必要有一个名称。每一个选择项都有一个名称和值，被提交到它被编写的章节里面。

Syntax:

  config       [""]      # Section
      option   ""       # Option

Every parameter needs to be a single string and is formatted exactly like a parameter for a shell function. The same rules for Quoting and special characters also apply, as it is parsed by the shell.

每一个参量都是一个单一的字符串对象，其格式和SHELL功能的参量完全一样。引用同样的规则和特殊字符都可以运用，因为它是由SHELL解析的。

Parsing configuration files in custom scripts

To be able to load configuration files, you need to include the common functions with:

为了写入配置文件，你需要包括以下的常见功能：

  . /etc/functions.sh

Then you can use config_load to load config files. The function first checks for as absolute filename and falls back to loading it from /etc/config (which is the most common way of using it).

然后你可以使用config_load 来写入配置文件。该功能首先把认为是绝对的文件名，然后回落，从/etc/config进行编写（这是最常用的方式）

If you want to use special callbacks for sections and/or options, you need to define the following shell functions before running config_load (after including /etc/functions.sh):

如果你想针对章节或选择项使用特殊的回调函数，在运行config_load (在包含/etc/functions.sh之后)之前，你需要确定SHELL功能。

  config_cb() {
      local type="$1"
      local name="$2"
      # commands to be run for every section
  }
  
  option_cb() {
      # commands to be run for every option
  }

You can also alter option_cb from config_cb based on the section type. This allows you to process every single config section based on its type individually.

你可以根据片段类型，更改来自config_cb的option_cb。这让你可以根据其类型，处理不同的配置片段。

config_cb is run every time a new section starts (before options are being processed). You can access the last section through the CONFIG_SECTION variable. Also an extra call to config_cb (without a new section) is generated after config_load is done. That allows you to process sections both before and after all options were processed.

Another way of iterating on config sections is using the config_foreach command.

config_cb每次都运行一个新的片段(在选择项被处理之前)。你可以用CONFIG_SECTION变量访问最后一个章节。config_load 完成之后，将产生一个到config_cb（不带新的章节）的呼叫。这样一来，你就可以在所有选项都处理前或后，处理片段了。另一种迭代配置片段的方式是使用config_foreach指令。

Syntax:

  config_foreach  [] []

This command will run the supplied function for every single config section in the currently loaded config. The section name will be passed to the function as argument 1. If the section type is added to the command line, the function will only be called for sections of the given type.

该指令将在当前加载的配置里，运行每一个简单配置片段的功能。该片段的名称将作为参数1,将传输到一些功能上。如果片段类型添加到了指令行，这些功能将针对给定类型的片段被呼叫。

You can access already processed options with the config_get command Syntax:

你可以用config_get命令语法访问已经处理的选项。

  # print the value of the option
  config_get 

 
  
  # store the value inside the variable
  config_get  

 

In busybox ash the three-option config_get is faster, because it does not result in an extra fork, so it is the preferred way.

Additionally you can also modify or add options to sections by using the config_set command.

在命令集里面，3个选项合一的config_get运行速度较快，因为它不会产生额外的子进程，因而也是最佳方式。

此外，你还需要通过使用config_set指令，修改或增加选项到片段里。

Syntax:

  config_set 

  

If a config section is unnamed, an automatically generated name will be assigned internally, e.g. cfg1, cfg2, ...

如果一个配置片段没有命名，在内存上将自动生成一个名字。例如，cfg1, cfg2, ...

While it is possible, using unnamed sections through these autogenerated names is strongly discouraged. Use callbacks or config_foreach instead.

但如果有可能，尽量不使用这些没有命名，而自动生成名字的片度。使用回叫信号或config_foreach代替。

1.3.1 Hotplug

1.3.2 Init scripts

Because OpenWrt uses its own init script system, all init scripts must be installed as /etc/init.d/name use /etc/rc.common as a wrapper.

OpenWrt使用它的初始化脚本系统，因此所有的初始化脚本必须安装成/etc/init.d/name use /etc/rc.common作为包装器。

Example: /etc/init.d/httpd

  #!/bin/sh /etc/rc.common
  # Copyright (C) 2006 OpenWrt.org
  
  START=50
  start() {
      [ -d /www ] && httpd -p 80 -h /www -r OpenWrt
  }
  
  stop() {
      killall httpd
  }

as you can see, the script does not actually parse the command line arguments itself. This is done by the wrapper script /etc/rc.common.

你可以看出，脚本自己并未解析指令行的参数。这由包装器脚本/etc/rc.common完成。

start() and stop() are the basic functions, which almost any init script should provide. start() is called when the user runs /etc/init.d/httpd start or (if the script is enabled and does not override this behavior) at system boot time.

start()和stop()都是基本功能，几乎所有的初始化脚本都能提供。当用户运行/etc/init.d/httpd start 或系统启动时（如果脚本能够并且不取代该行为），start()被呼叫。

Enabling and disabling init scripts is done by running /etc/init.d/name enable or /etc/init.d/name disable. This creates or removes symbolic links to the init script in /etc/rc.d, which is processed by /etc/init.d/rcS at boot time.

通过运行/etc/init.d/name enable 或 /etc/init.d/name disable可是初始化脚本有效或失效。这将生成或清除/etc/rc.d里初始化脚本的符号连接，在启动时由/etc/init.d/rcS处理。

The order in which these scripts are run is defined in the variable START in the init script. Changing it requires running /etc/init.d/name enable again.

这些脚本运行的顺序是由初始化脚本里面的START变量定义的。改变它需要再度运行/etc/init.d/name enable。

You can also override these standard init script functions:

你可以覆盖标准的初始化脚本的功能。

• boot()
  Commands to be run at boot time. Defaults to start()
• 在启动时运行的指令，默认是start()。
• restart()
  Restart your service. Defaults to stop(); start()
• 重启你的服务内容，默认是stop(); start()
• reload()
  Reload the configuration files for your service. Defaults to restart()
• 重新为服务内容载入配置文件。默认是restart()

You can also add custom commands by creating the appropriate functions and referencing them in the EXTRA_COMMANDS variable. Helptext is added in EXTRA_HELP.

你还可以通过创建合适的功能，在EXTRA_COMMANDS参数中引用，来增加自定义指令。帮助说明添加到EXTRA_HELP里。

Example:

  status() {
      # print the status info
  }
  
  EXTRA_COMMANDS="status"
  EXTRA_HELP="        status  Print the status of the service"

1.3.3 Network scripts

Using the network scripts

To be able to access the network functions, you need to include the necessary shell scripts by running:

要能够访问网络功能，你需要运行以下指令，来包含必要的SHELL脚本。

  . /etc/functions.sh      # common functions
  include /lib/network     # include /lib/network/*.sh
  scan_interfaces          # read and parse the network config

Some protocols, such as PPP might change the configured interface names at run time (e.g. eth0 => ppp0 for PPPoE). That’s why you have to run scan_interfaces instead of reading the values from the config directly. After running scan_interfaces, the ’ifname’ option will always contain the effective interface name (which is used for IP traffic) and if the physical device name differs from it, it will be stored in the ’device’ option. That means that running config_get lan ifname after scan_interfaces might not return the same result as running it before.

一些协议，例如PPP可以在运行时改变配置界面(e.g. eth0 => ppp0 for PPPoE).这就是你为何不能直接从配置文件里读取数值而要运行scan_interfaces的原因。在运行scan_interfaces之后，’ifname’选项将常常含有有效的界面名称（这是针对IP流量使用的），如果物理设备的名称和它不太，它将被存储在’device’选项。这表明在scan_interfaces 后运行config_get lan ifname可能和先前运行得到的结果不一样。

After running scan_interfaces, the following functions are available:

运行scan_interfaces后，可获得以下功能：

• find_config interface
  looks for a network configuration that includes the specified network interface.
• 寻找包含特定网络界面的网络配置。
• setup_interface interface [config] [protocol]
  will set up the specified interface, optionally overriding the network configuration name or the protocol that it uses.
• 将设置指定的界面，选择项的覆盖网路配置名称或它使用的协议。

Writing protocol handlers

You can add custom protocol handlers by adding shell scripts to /lib/network. They provide the following two shell functions:

你可以通过添加SHELL脚本到/lib/network来增加自定义协议处理器。它们将提供以下2中SHELL 功能。

  scan_() {
      local config="$1"
      # change the interface names if necessary
  }
  
  setup_interface_() {
      local interface="$1"
      local config="$2"
      # set up the interface
  }

scan_protocolname is optional and only necessary if your protocol uses a custom device, e.g. a tunnel or a PPP device.

scan_protocolname是选择性的，如果你使用了一个自定义设置，那它将成为必须的。例如，一个加密链路乎PPP装置。