ansible-openwisp2-imagegenerator

このansibleロールは、異なる組織向けに複数のopenwisp2ファームウェアイメージをビルドし、その設定を追跡できるようにします。

注意: このロールはまだ実際の環境ではテストされていません。 使用する予定であれば、試してみて、何か問題が発生した場合は問題を報告してください。ただし、ビルドプロセスおよび内部動作を理解することが必要です。

必要なロール変数

以下の変数が必要です：

• openwisp2fw_source_dir: OpenWRTソースのディレクトリを示します。
• openwisp2fw_generator_dir: ジェネレーターの準備に使用されるディレクトリを示します。
• openwisp2fw_bin_dir: 最終イメージのビルドに使用されるディレクトリを示します。
• openwisp2fw_organizations: 組織のリスト；その構造を理解するために、プレイブック作成セクションの例 playbook.yml ファイルをご覧ください。

使用方法（チュートリアル）

ansibleの使い方がわからない場合は、パニックにならず、手順を一つずつ説明します。

ansibleの使い方を既に知っている場合は、このセクションをスキップし、「このロールのインストール」セクションに進んでください。

まず、2つの重要な概念を理解する必要があります：

• 「コンパイルサーバー」: イメージをコンパイルするために使用されるサーバーを指します。
• 「ローカルマシン」: ansibleを起動するホスト、例えばあなたのラップトップやCIサーバーを指します。

Ansibleは、SSHを介してコンパイルサーバーにアクセスし、一連のコマンドを実行する構成管理/自動化ツールです。

1. ansibleのインストール

まだインストールしていない場合は、ローカルマシンに ansibleをインストールする必要があります。公式のPythonパッケージマネージャを使用するのが一般的です。例えば：

sudo pip install ansible

pipがインストールされていない場合は、pipのインストールを確認してください。

別の方法でansibleをインストールすることもできますので、2.0.xシリーズのバージョンをインストールしてください（このプレイブックをテストしたバージョンです）。

2. このロールをインストール

簡単のために、このロールはローカルマシンに ansible-galaxyを介してインストールするのが最も簡単です（ansibleをインストールしたときにインストールされました）。次のコマンドを実行してください：

sudo ansible-galaxy install openwisp.openwisp2-imagegenerator

3. 作業ディレクトリを選択

ファームウェアイメージの設定を置くための作業ディレクトリをローカルマシンに選択してください。

例：

mkdir ~/my-openwisp2-firmware-conf
cd ~/my-openwisp2-firmware-conf

この作業ディレクトリをバージョン管理下に置くことは非常に良いアイデアです。変更を追跡したり、ロールバックしたり、CIサーバーを設定して自動的にイメージをビルドするのに役立ちます。

4. インベントリファイルを作成

インベントリファイルはグループサーバーが定義されている場所です。簡単な場合、1台のサーバーを入れるグループを定義するだけで済みます。

次の内容で hosts という新しいファイルをローカルマシンに作成してください：

[myserver]
mycompiler.mydomain.com ansible_user=<youruser> ansible_become_pass=<sudo-password>

mycompiler.mydomain.comをあなたのホスト名に置き換えてください（IPアドレスも許可されています）。

また、 と のそれぞれの部分にあなたのSSHユーザーとパスワードを置いてください（sudoerで非rootである必要があります）。これらの資格情報は、依存関係のインストールステップ中に使用されます。

5. プレイブックファイルを作成

次の内容で playbook.yml という新しいプレイブックファイルをローカルマシンに作成してください：

# playbook.yml
- hosts: your_host_here
  roles:
    - openwisp.openwisp2-imagegenerator
  vars:
    openwisp2fw_source_dir: /home/user/openwisp2-firmware-source
    openwisp2fw_generator_dir: /home/user/openwisp2-firmware-generator
    openwisp2fw_bin_dir: /home/user/openwisp2-firmware-builds
    openwisp2fw_source_targets:
        - system: ar71xx
          subtarget: generic
          profile: Default
        - system: x86
          subtarget: generic
          profile: Generic
    openwisp2fw_organizations:
        - name: snakeoil # 組織の名前
          flavours: # サポートされているフレーバー
            - standard
          luci_openwisp: # /etc/config/luci_openwisp
            # その他の設定キーは自由に追加可能
            username: "operator"
            # /etc/config/luci_openwispで暗号化されるプレーンテキストパスワード
            password: "<CHANGE_ME>"
          openwisp: # /etc/config/openwisp
            # その他の設定キーは自由に追加可能
            url: "https://my-openwisp2-instance.com"
            shared_secret: "my-openwisp2-secret"
            unmanaged: "{{ openwisp2fw_default_unmanaged }}"
          # /etc/shadowで暗号化されるプレーンテキストパスワード
          root_password: "<CHANGE_ME>"

このプレイブックでは、snakeoilという名前の組織用に、標準フレーバーのみを使用してファームウェアイメージをコンパイルすることができます（デフォルトのOpenWRT 19.07イメージと標準のOpenWISP2モジュールが含まれています）。

利用可能な設定をカスタマイズする方法については、ロール変数のセクションを参照してください。

この時点で、あなたのディレクトリの構成は次のようになるはずです：

.
├── hosts
└── playbook.yml

6. プレイブックを実行

今こそ、OpenWISP2ファームウェアのコンパイル*を開始する時です。

次のコマンドでローカルマシンからプレイブックを起動します：

ansible-playbook -i hosts playbook.yml -e "recompile=1 cores=4"

cores=4の部分は、利用可能なコアの数に置き換えてください。

プレイブックの実行が完了すると、指定した openwisp2fw_bin_dir内（この例では /home/user/openwisp2-firmware-builds）で、次のようなディレクトリ構成でイメージが見つかります：

/home/user/openwisp2-firmware-builds
├── snakeoil/                                      # (各組織には独自のディレクトリがあります)
├── snakeoil/2016-12-02-094316/ar71xx/standard/    # (標準フレーバーのar71xxイメージが含まれています)
├── snakeoil/2016-12-02-094316/x86/standard/       # (標準フレーバーのx86イメージが含まれています)
└── snakeoil/latest/                               # (latestは最後のコンパイルへのシンボリックリンクです)

このチュートリアルに従い、すべてがうまくいった場合、あなたのニーズに合うように設定をカスタマイズする準備が整いました！この後、次の方法を読み進めてください。

ロール変数

必要に応じてカスタマイズできる多くの変数があります。包括的なリストについては、 デフォルトを確認してください。

これらの変数の一部は、組織やフレーバーにも説明されています。

組織

OpenWISPで作業している場合、異なるグループの人々のためにイメージをコンパイルしている可能性があります：営利顧客、非営利組織、または "組織"として定義できる任意の人々のグループです。

openwisp2fw_organizationsで組織を自由に定義できます。

これを行う方法の例については、"例のplaybook.ymlファイル"を参照してください。

特定の組織のファイルをファイルシステムツリーに追加する必要がある場合は、 "特定の組織のためのファイルの追加"を参照してください。

フレーバー

フレーバーは、イメージに含まれるパッケージの組み合わせです。

異なるイメージのために異なるフレーバーを作成したいかもしれません。例えば：

• standard: 最も一般的な使用例
• minimal: ストレージスペースが限られたデバイス用のイメージ
• mesh: メッシュネットワークを実装するために必要なパッケージを含むイメージ

デフォルトでは、standardフレーバーのみが利用可能です。

自分自身のフレーバーを定義するには、openwisp2fw_image_flavoursを設定してください。構造を理解するために、デフォルト変数を見てください。

ビルドプロセス

ビルドプロセスは、以下のステップで構成されています。

1. 依存関係のインストール

タグ: install

この段階では、次のステップに必要なオペレーティングシステムの依存関係がインストールまたはアップグレードされます。

2. コンパイル

タグ: compile

OpenWRTソースをコンパイルして、"イメージジェネレーター"と呼ばれるものを生成します。このイメージジェネレーターは、プリコンパイルされたパッケージと、各組織のカスタマイズされたイメージを生成するために使用される特別な Makefile を含むアーカイブです。

ソースは、openwisp2fw_source_dirに指定されたディレクトリにダウンロードされてコンパイルされます。

3. ジェネレーターの準備

タグ: generator

このステップでは、イメージジェネレーターが抽出され、異なる組織向けに異なるイメージをビルドするために準備されます。各組織は異なるフレーバーのイメージをビルドできます（例：フル機能、ミニマル、メッシュなど）。

イメージは、openwisp2fw_generator_dirに指定されたディレクトリに抽出されて準備されます。

4. 最終イメージのビルド

タグ: build

この段階では、一連のイメージが生成されます。

各アーキテクチャ、組織、フレーバーに対して複数のイメージがビルドされます。たくさんのファイルが生成される可能性があるため、この機能を慎重に使用してください。最初は少ないオプションで始め、進むにつれてさらに多くのケースを追加するのが良いでしょう。

例えば、2つのアーキテクチャ（ar71xxとx86）、2つの組織（例えば、AとB）、2つのフレーバー（例えば、standardとmini）を使用すると、8つのイメージグループが生成されます：

• 組織: A / フレーバー: standard / アーキテクチャ: ar71xx
• 組織: A / フレーバー: standard / アーキテクチャ: x86
• 組織: A / フレーバー: mini / アーキテクチャ: ar71xx
• 組織: A / フレーバー: mini / アーキテクチャ: x86
• 組織: B / フレーバー: standard / アーキテクチャ: ar71xx
• 組織: B / フレーバー: standard / アーキテクチャ: x86
• 組織: B / フレーバー: mini / アーキテクチャ: ar71xx
• 組織: B / フレーバー: mini / アーキテクチャ: x86

イメージは、openwisp2fw_bin_dirに指定されたディレクトリに作成されます。

5. OpenWISPファームウェアアップグレーダーにイメージをアップロード

最後のステップは、OpenWISPファームウェアアップグレーダーモジュールにイメージをアップロードすることです。このステップはオプションで、デフォルトでは無効です。

この機能を有効にするには、変数 openwisp2fw_uploader と openwisp2fw_organizations.categories を次のように設定する必要があります：

- hosts:
    - myhost
  roles:
    - openwisp.openwisp2-imagegenerator
  vars:
    openwisp2fw_controller_url: "https://openwisp.myproject.com"
    openwisp2fw_organizations:
      - name: staging
        flavours:
          - default
        openwisp:
          url: "{{ openwisp2fw_controller_url }}"
          shared_secret: "xxxxx"
        root_password: "xxxxx"
        categories:
          default: <CATEGORY-UUID>
      - name: prod
        flavours:
          - default
        openwisp:
          url: "{{ openwisp2fw_controller_url }}"
          shared_secret: "xxxxx"
        root_password: "xxxxx"
        categories:
          default: <CATEGORY-UUID>
    openwisp2fw_uploader:
        enabled: true
        url: "{{ openwisp2fw_controller_url }}"
        token: "<REST-API-USER-TOKEN>"
        image_types:
            - ath79-generic-ubnt_airrouter-squashfs-sysupgrade.bin
            - ar71xx-generic-ubnt-bullet-m-xw-squashfs-sysupgrade.bin
            - ar71xx-generic-ubnt-bullet-m-squashfs-sysupgrade.bin
            - octeon-erlite-squashfs-sysupgrade.tar
            - ath79-generic-ubnt_nanostation-loco-m-xw-squashfs-sysupgrade.bin
            - ath79-generic-ubnt_nanostation-loco-m-squashfs-sysupgrade.bin
            - ath79-generic-ubnt_nanostation-m-xw-squashfs-sysupgrade.bin
            - ar71xx-generic-ubnt-nano-m-squashfs-sysupgrade.bin
            - ath79-generic-ubnt_unifiac-mesh-squashfs-sysupgrade.bin
            - x86-64-combined-squashfs.img.gz
            - x86-generic-combined-squashfs.img.gz
            - x86-geode-combined-squashfs.img.gz
            - ar71xx-generic-xd3200-squashfs-sysupgrade.bin

例の中の以下のプレースホルダーを置き換える必要があります：

• <CATEGORY-UUID>はOpenWISPファームウェアアップグレーダー内のファームウェアカテゴリのUUIDです。
• <REST-API-USER-TOKEN>はイメージをアップロードする権限を持つユーザーのREST認証トークンです。

REST認証トークンは、OpenWISPのブラウザAPIウェブインターフェースを使用してPOSTリクエストを送ることで取得できます：

1. ブラウザで https://<openwisp-base-url>/api/v1/user/token/を開きます。
2. ページ下部のフォームにユーザー名とパスワードを入力します。
3. フォームを送信すると、レスポンスにREST認証トークンが返されます。

アップロードスクリプトは、新しいビルドオブジェクトを作成し、その後、image_typesに指定されたファームウェアイメージをアップロードします。

これらのイメージは、OpenWISPファームウェアアップグレーダーのhardware.pyファイル内で定義されている識別子のように、イメージのアップロードスクリプトによって指定されたものと一致する必要があります。

upload_firmware.pyスクリプトに関するその他の重要な点：

• このスクリプトは、OpenWRTソースコードの.configファイルからCONFIG_VERSION_DISTとCONFIG_VERSION_NUMBERを読み取り、ビルドバージョンを決定します。
• このスクリプトは、同じバージョンとカテゴリのビルドが既に存在するかを確認し、新しいビルドを作成するのではなく、そのビルドにイメージを追加しようとします。重複が見つかった場合、失敗メッセージがコンソールに表示されますが、スクリプトは終了しません。これにより、新しいハードウェアモデルのイメージを生成し、既存のビルドに追加することができます。

イメージにファイルを追加

生成されたすべてのイメージに任意のファイルを追加するには、プレイブックディレクトリ内に files/ という名前のディレクトリを作成し、その中にファイルを配置してください。

例：

.
├── hosts
├── playbook.yml
└── files/etc/profile

files/etc/profileは、生成されるすべてのイメージに追加されます。

特定の組織のためにファイルを追加

特定の組織のイメージにファイルを追加することもできます。

例えば、snakeoilという組織があり、カスタムバナーを追加したいとします。次のディレクトリ構造を作成すれば実現できます。

.
├── hosts
├── playbook.yml
└── organizations/snakeoil/etc/banner

このステップは最終イメージのビルド直前に実行されるステップの一つであるため、これを利用して前のステップで自動的にビルドされたファイルを上書きすることができます。

追加のパラメータ

以下の追加パラメータを ansible-playbook に渡すことができます：

• recompile: コンパイルステップを繰り返すかどうか
• cores: コンパイルステップで使用するコアの数
• orgs: 特定の組織の生成制限が必要な場合の組織名のカンマ区切りリスト

例

16コアで再コンパイル:

ansible-playbook -i hosts playbook.yml -e "recompile=1 cores=16"

組織fooのためにのみイメージを生成:

ansible-playbook -i hosts playbook.yml -e "orgs=foo"

組織fooとbarのためにのみイメージを生成:

ansible-playbook -i hosts playbook.yml -e "orgs=foo,bar"

特定のステップを実行

プロセス内の各ステップにはタグが付いているため、ansibleタグを使用して特定のステップを実行できます。

例1、ジェネレーターの準備だけを実行:

ansible-playbook -i hosts playbook.yml -t generator

例2、ジェネレーターの準備とビルドステップだけを実行:

ansible-playbook -i hosts playbook.yml -t generator,build

サブターゲットのないターゲット

この例では、サブターゲットを指定しないターゲットをコンパイルするための openwisp2fw_source_targets の記入方法を示します（例：sunxi, ARMv8, QEMU）：

openwisp2fw_source_targets:
    # Allwinner SOC, Lamobo R1
    - system: sunxi
      profile: sun7i-a20-lamobo-r1
    # QEMU ARM仮想イメージ
    - system: armvirt
      profile: Default

サポート

OpenWISPサポートチャンネルをご覧ください。