メーカーパックの書き方

ConfigChief の本体は、メーカーを知りません。コンフィグの読み方・書き方・語の対応は、すべて「メーカーパック」というフォルダ(YAML とテンプレートのテキスト)にあります。新しいメーカーや新しい設定は、パックを足す・直すことで対応します。プログラムは直しません。

同梱のパック(internal/packs/cisco_ios・internal/packs/nec_ix)が、いちばんの見本です。このページと並べて読んでください。

1. はじめに決まりを 4 つ

  1. 確かめていない書き方は、規則にしない。 読めない行は「未対応」として人に見えます。誤って読むより安全です。メーカーが公開しているコマンドリファレンスで構文を確かめ、資料の名前と版を README に書きます
  2. 取り込みの規則とテンプレートは、対で書く。 書き出した文面を同じパックで読み直し、元の表と同じになることを、ツールが毎回確かめます(往復の確認)
  3. 黙って落とさない。 設定として意味のある行を「無視」に入れてはいけません。書けない値は、テンプレートで理由と直し方を付けて止めます
  4. 見本は架空の値で書く。 アドレスは例示用(192.0.2.0/24・198.51.100.0/24・203.0.113.0/24・2001:db8::/32)、AS 番号は 64496〜64511、名前は example.com・rt-a01 のような自作のものを使います。現場で見た値は、形を変えても使いません

2. 作って試す

packs/<パックの ID>/
  pack.yaml        基本の情報、メーカーの判定、文面の形、IF 名、端末ログの切り出し
  ignore.yaml      無視する行
  import/*.yaml    取り込みの規則(ファイル名の順に読む)
  defaults.yaml    行が無いときの機器の動き(既定値)
  lexicon.yaml     語の対応(中立の語 ↔ メーカーの語)
  render.yaml      コンフィグを書く順番
  templates/*.j2   テンプレート
  adapt.yaml       このメーカーの書き方への置き換え(要るときだけ)
  errors.yaml      機器のエラーメッセージの形(投入ログのチェック用)
  words.txt        コマンドの語(未対応の行の持ち出し用レポートで残す語。無くてもよい)
  tests/import/<名前>/input.txt, expect.yaml
  tests/render/<名前>/data.yaml, expect.txt
  README.md        対応の一覧、参照した資料、確かめていないこと

3. pack.yaml

id: sample_os
title: {ja: "見本の OS", en: "Sample OS"}
version: 0.1.0
schema: 1
syntax: indent                  # indent = 字下げで親子が決まる。flat = すべての行が同じ階層
comment_prefixes: ["!"]
output: {encoding: utf-8, newline: lf, indent: " "}
end_marker: '^end$'             # 無ければ「途中で切れている疑い」と知らせる

detect:                         # 当たった行の点を足し、合計の高いパックを選ぶ
  - {match: '^interface GigabitEthernet\d', score: 2}
  - {match: '^line vty \d+', score: 2}

hostname: '^hostname (?P<name>\S+)$'

interfaces:
  types:
    - {name: GigabitEthernet, short: [Gi, Gig], kind: physical}
    - {name: Loopback, short: [Lo], kind: loopback}
    - {name: Tunnel, short: [Tu], kind: tunnel}
  subif: '^(?P<parent>.+)\.(?P<n>\d+)$'

session:                        # 端末ログから、設定の部分だけを切り出す
  prompt: '^(?P<host>[\w.\-]+)(\((?P<mode>[^)]+)\))?[>#]'
  show_config: ['^show running-config$']
  pager: ['--More--']

4. 取り込みの規則(import/*.yaml)

rules:
  - id: if
    match: '^interface (?P<name>\S+)$'
    row: {table: interfaces, key: {name: "{{ name | ifname }}"}}
    children:
      - id: if.description
        match: '^description (?P<v>.+)$'
        set: {description: "{{ v }}"}
      - id: if.ipv4
        match: '^ip address (?P<ip>\S+) (?P<mask>\S+)$'
        set: {ipv4: "{{ ip | with_mask(mask) }}"}
      - id: if.ipv4.secondary
        match: '^ip address (?P<ip>\S+) (?P<mask>\S+) secondary$'
        append: {ipv4_secondary: "{{ ip | with_mask(mask) }}"}
      - id: if.shutdown
        match: '^shutdown$'
        set: {enabled: false}
項目内容
id規則の名前(パックの中で 1 つ)。行の対応と試験に出ます
match正規表現(Go の RE2)。行の全体に当てるので ^ と $ を書きます。(?P<名前>…) で取った値が変数になります
when追加の条件(式)。偽なら、当たらなかったことにします
row行を開きます(table と key)。同じキーの行があれば、その行に足します
set開いている行の列に値を入れます。空になった値は入れません
append複数の値を持つ列に値を足します(空白とカンマで区切って、その数だけ)
emit別の表に行を作ります(table・key・set・append)
children子の行に当てる規則
children_from別の規則の ID。その規則の children を、ここでも使います
ignore理由の文。この行を「無視」にします(子の行の中で使います)

当て方の決まり:

式({{ }} の中と when)は Jinja2 の書き方です。取り出した名前のほか、parent(直近の親の規則で取った値)、row(開いている行)、device(ホスト名)が使えます。

4.1 無視する行(ignore.yaml)

ignore:
  - {match: '^Building configuration', reason: 表示上の行}
  - {match: '^version \d', reason: 機器が自動で付ける行}
  - {match: '^end$', reason: 終わりの印}

入れてよいのは、表示上の行・機器が自動で付ける行・終わりの印だけです。

4.2 分かれて書かれた設定をまとめる(derive)

1 つの設定がいくつかの場所に分かれているメーカーでは、いったん作業用の表(名前が x_ で始まる。列は自由)に入れ、すべての行を読み終えてからまとめます。

derive:
  - id: nat.pool.join
    for: x_nat_use                # 作業用の表の 1 行ずつを u として回す
    as: u
    let:
      pool: "lookup('x_nat_pool', name=u.pool)"
    when: "pool.start"
    row: {table: nat_rules, key: {name: "{{ u.name }}"}}
    set: {pool_start: "{{ pool.start }}", pool_end: "{{ pool.end }}"}

4.3 既定値(defaults.yaml)

defaults:
  - {table: interfaces, column: enabled, value: true}
  - {table: ospf_interfaces, column: hello, value: 10, when: "row.network_type in ['broadcast', '']"}

行が無いときの機器の動きを書きます。取り込みでは空の列を埋め、書き出しでは「明示」の列が空のときに使います。コマンドリファレンスで確かめた値だけを書きます。

4.4 語の対応(lexicon.yaml)

ike_encryption:          # 種類の名前
  aes256: "aes 256"      # 中立の語: メーカーの語
  aes128: aes

テンプレートでは {{ r.ike_encryption | lex('ike_encryption') }}(中立 → メーカー)、取り込みでは {{ v | unlex('ike_encryption') }}(メーカー → 中立)と書きます。対応が無い語は、取り込みでは「未対応」、書き出しではエラー(G-603)になります。

5. 書き出し(render.yaml と templates/)

# render.yaml
sections:
  - {id: system,     template: system.j2}
  - {id: interfaces, template: interfaces.j2}
  - {id: extra,      slot: extra}       # 追加コンフィグが入る場所
  - {id: footer,     template: footer.j2}
{# templates/interfaces.j2 #}
{% for i in t.interfaces %}
interface {{ i.name }}
{% if i.description %}
 description {{ i.description }}
{% endif %}
{% if i.ipv4 is cidr %}
 ip address {{ i.ipv4 | ip }} {{ i.ipv4 | mask }}
{% endif %}
{% if i.enabled == false %}
 shutdown
{% endif %}
!
{% endfor %}

テンプレートで使える値: device(機器の行)、t.表の名前(その機器の行の並び)、all.表の名前(全機器の行。相手の値を引くとき)、project(案件の設定)。

フィルタ・関数内容
ip / mask / wildcard / prefixlen / network / broadcast192.0.2.1/30 から、アドレス・マスク・ワイルドカード・長さ・ネットワーク・ブロードキャスト
with_mask(m) / with_wildcard(w)アドレスとマスク(ワイルドカード)から アドレス/長さ を作る
ifname / ifshortIF 名を正式な形/省略形にする
lex(種類) / unlex(種類)語の対応
required(文)空ならエラーにする(G-606)。例 {{ r.outside_if | required('外側 IF') }}
fail(文)エラーにして止める(G-601)。文には、理由と直し方を書きます
is cidr / is digits値が「アドレス/長さ」の形か/数字だけか

書くときの決まり:

読まなかった値は、G-602 として指摘されます。 表に値があるのに、どのテンプレートも読まなかったセルです。別メーカーから来た値を、このパックが書けないときに出ます。「このメーカーには無い設定」と宣言して黙らせる仕組みは、わざと作っていません。

5.1 このメーカーの書き方への置き換え(adapt.yaml)

表にある設定を、このメーカーが別の形でなら書けるとき、パックが書き出しの前に行を置き換えられます。置き換えたことは、必ず G-614(警告)で知らせます。

adapt:
  - id: qos.remaining
    for: qos_policies
    as: p
    when: "p.bandwidth_remaining"
    row: {table: qos_policies, key: {policy: "{{ p.policy }}", class: "{{ p.class }}"}}
    set: {bandwidth_percent: "{{ p.bandwidth_remaining }}"}
    clear: [bandwidth_remaining]
    note: "「帯域(残りの %)」はこの機種に無いので、「帯域(%)」として書きます"

6. 試験

# tests/import/basic/expect.yaml
tables:
  interfaces:
    - {name: GigabitEthernet0/0, description: sample wan, ipv4: 192.0.2.1/30, enabled: true}
unknown:                 # 「未対応」になるはずの行(これ以外が未対応になると不合格)
  - "ip sla 10"
# tests/render/basic/data.yaml
tables:
  devices:
    - {hostname: rt-a01, vendor: sample_os}
  interfaces:
    - {name: GigabitEthernet0/0, ipv4: 192.0.2.1/30, enabled: true}
findings: []             # 出るはずの指摘の ID(例 [G-601])。書かなければ「指摘なし」を期待

7. パックの検査

pack test と起動のときに、次を確かめます。誤りがあるパックは読み込みません。

8. README に書くこと

使う人が「取り込み済み」の意味を確かめられるように、次を書きます。