本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 為 Amazon EC2 Linux 執行個體開發 EC2Rescue 模組
<a name="ec2rl_moduledev"></a>

模組是使用 YAML (資料序列化標準) 撰寫。模組的 YAML 檔案是由單一文件組成，代表模組及其屬性。

## 新增模組屬性
<a name="ec2rl-adding-modules"></a>

下表列出可用的模組屬性。


| 屬性 | 描述 | 
| --- | --- | 
| name | 模組的名稱。此名稱長度應小於或等於 18 個字元。 | 
| version | 模組的版本編號。 | 
| title | 模組的簡述標題。此值長度應小於或等於 50 個字元。 | 
| helptext |  模組的延伸描述。各行長度應小於或等於 75 個字元。如果模組使用引數 (無論必要或選用)，請以 helptext 值包含它們。 例如： <pre>helptext: !!str |<br />  Collect output from ps for system analysis<br />  Consumes --times= for number of times to repeat<br />  Consumes --period= for time period between repetition</pre> | 
| placement | 應該執行模組的階段。支援的值為： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/AWSEC2/latest/UserGuide/ec2rl_moduledev.html)  | 
| 語言 | 撰寫模組程式碼的語言。支援的值為： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/AWSEC2/latest/UserGuide/ec2rl_moduledev.html)  Python 程式碼必須與 Python 2.7.9\$1 和 Python 3.2\$1 都相容。   | 
| remediation |  指出模組是否支援修補。支援的值為 `True` 或 `False`。 如果無此屬性，模組將預設為 `False`，讓其成為不支援修補之模組的選用屬性。  | 
| content | 完整的指令碼程式碼。 | 
| 限制條件 | 包含限制值的物件名稱。 | 
| domain | 說明模組如何分組或分類的描述項。包含的模組集使用下列網域： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/AWSEC2/latest/UserGuide/ec2rl_moduledev.html) | 
| class | 模組執行的任務類型描述項。包含的模組集使用下列類別： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/AWSEC2/latest/UserGuide/ec2rl_moduledev.html) | 
| distro | 此模組支援的 Linux 發行版本清單。包含的模組集使用下列發行版本： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/AWSEC2/latest/UserGuide/ec2rl_moduledev.html) | 
| 必要 | 模組從 CLI 選項使用的必要引數。 | 
| 選擇性 | 模組可以使用的選用引數。 | 
| software | 在模組中使用的軟體可執行檔。此屬性旨在指定非預設安裝的軟體。適用於 Linux 的 EC2Rescue 邏輯在執行模組前會確保這些程式存在並可執行。 | 
| package | 可執行檔的來源軟體套件。此屬性旨在提供套件有關軟體的延伸詳細資料，包括下載或取得未來資訊的 URL。 | 
| sudo | 指出是否一定要有根存取才能執行模組。 您不必在模組指令碼中實作 sudo 檢查。如果此值為 true，則當執行使用者有根存取時，適用於 Linux 的 EC2Rescue 邏輯只會執行模組。 | 
| perfimpact | 指出模組是否會顯著影響其執行所在環境的效能。如果此值為 true 且無 `--perfimpact=true` 引數，則跳過模組。 | 
| parallelexclusive | 指定需要互斥的程式。例如，所有指定 "bpf" 的模組都依序執行。 | 

## 新增環境變數
<a name="ec2rl_adding_envvars"></a>

下表列出可用的環境變數。


| 環境變數 | 描述 | 
| --- | --- | 
|  `EC2RL_CALLPATH`  | ec2rl.py 的路徑。此路徑可用以尋找 lib 目錄及使用經過廠商處理的 Python 模組。 | 
|  `EC2RL_WORKDIR`  |  診斷工具的主要 tmp 目錄。 預設值：`/var/tmp/ec2rl`。 | 
|  `EC2RL_RUNDIR`  |  存放所有輸出的目錄。 預設值：`/var/tmp/ec2rl/<date&timestamp>`。  | 
|  `EC2RL_GATHEREDDIR`  |  放置所收集模組資料的根目錄。 預設值：`/var/tmp/ec2rl/<date&timestamp>/mod_out/gathered/`。  | 
|  `EC2RL_NET_DRIVER`  |  執行個體上按字母順序第一個非虛擬網路界面使用的驅動程式。 範例: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/AWSEC2/latest/UserGuide/ec2rl_moduledev.html)  | 
|  `EC2RL_SUDO`  |  如果適用於 Linux 的 EC2Rescue 執行為根，即為 true；否則為 false。  | 
|  `EC2RL_VIRT_TYPE`  |  如執行個體中繼資料所提供的虛擬化類型。 範例： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/AWSEC2/latest/UserGuide/ec2rl_moduledev.html)  | 
|  `EC2RL_INTERFACES`  |  系統上的界面列舉清單。值是包含名稱的字串，例如 `eth0`、`eth1` 等等。這是透過 `functions.bash` 產生的，僅供其來源模組使用。  | 

## 使用 YAML 語法
<a name="ec2rl_yamlsyntax"></a>

建構您的模組 YAML 檔案時，應該注意下列各點：
+ 三個連字號 (`---`) 表示文件的明確開頭。
+ 從資料串流建立物件時，`!ec2rlcore.module.Module` 標籤會告訴 YAML 剖析器要呼叫哪個建構函數。您可於 `module.py` 檔案中找到建構函數。
+ `!!str` 標籤會告訴 YAML 剖析器不要嘗試判斷資料類型，改將內容解譯為字串常值。
+ 管道字元 (`|`) 會告訴 YAML 剖析器此值為常值型純量。在本例中，剖析器包含所有空格。這對模組而言很重要，因為會保留縮排和換行字元。
+ YAML 標準會縮排兩格，如下列範例所示。請確定您的指令碼保持標準縮排 (例如，Python 四格)，然後在模組檔案中將完整內容縮排兩格。

## 範例模組
<a name="ec2rl_example"></a>

範例一 (`mod.d/ps.yaml`)：

```
--- !ec2rlcore.module.Module
# Module document. Translates directly into an almost-complete Module object
name: !!str ps
path: !!str
version: !!str 1.0
title: !!str Collect output from ps for system analysis
helptext: !!str |
  Collect output from ps for system analysis
  Requires --times= for number of times to repeat
  Requires --period= for time period between repetition
placement: !!str run
package: 
  - !!str
language: !!str bash
content: !!str |
  #!/bin/bash
  error_trap()
  {
      printf "%0.s=" {1..80}
      echo -e "\nERROR:	"$BASH_COMMAND" exited with an error on line ${BASH_LINENO[0]}"
      exit 0
  }
  trap error_trap ERR

  # read-in shared function
  source functions.bash
  echo "I will collect ps output from this $EC2RL_DISTRO box for $times times every $period seconds."
  for i in $(seq 1 $times); do
      ps auxww
      sleep $period
  done
constraint:
  requires_ec2: !!str False
  domain: !!str performance
  class: !!str collect
  distro: !!str alami ubuntu rhel suse
  required: !!str period times
  optional: !!str
  software: !!str
  sudo: !!str False
  perfimpact: !!str False
  parallelexclusive: !!str
```