Netbox Discovery でネットワーク機器の情報を自動登録する

Netbox Discovery を利用してネットワークデバイスの情報を NetBox へ自動登録をおこなってみたときのメモ
こちらを利用して、稼働している機器からデバイス情報やインターフェースや IP アドレスなどを自動で取得と登録ができました

Netbox Discovery とは

• NetBox Discovery は、ネットワーク機器の情報や設定を自動収集し、NetBox のインベントリを最新に保つ仕組み
• 構成は orb-agent、Diode サーバ、NetBox プラグインの3つだけで完結
• orb-agent は複数の収集モードに対応し、Nmap・NAPALM・SNMP・API連携など柔軟な取得が可能
• シンプルな構成で導入でき、定期的な自動取り込みにより構成管理や監査を効率化

全体的の構成イメージは以下となります

今回やったこと

ネットワークデバイスとして、Juniper と Arista のデバイスを Netbox Discovery を利用して、NetBox へ自動登録をやってみました
ネットワークシュミレーターで以下の構成を作って試しました

NetBox 関連のサーバー 2 台と、ネットワークデバイスとして vJunosSwitch (Juniper) と vEOS (Arista) を準備しました
各バージョンは以下となります

• Ubuntu : 24.04.2 LTS
• NetBox関連
  • NetBox : v4.3.5
  • Diode NetBox Plugin : v1.2.1
  • diode-ingester (Diode Server) : v1.4.0
  • Discovery agent (orb-agent) : v2.3.0
• vJunosSwitch : 24.4R1.9
• Arista vEOS-lab : 4.34.0F

全体構成

サーバー2台の構成は以下のイメージで、左の NetBox-SV 内に NetBox と Diode Server を同居させています
また、NetBox と Diode Server 間で通信できるように、同じ Docker Network (今回は「netbox-nw」) にいれました

構築 ( NetBox-SV )

Docker Network 作成

NetBox-SV 上で、NetBox と Diode Server を所属させるネットワークnetbox-nwを以下もコマンドで事前に作成

docker network create netbox-nw

作成した Docker Network はdocker network lsで確認できます

Diode サーバー

NetBox-SV 上で、orb-agentから情報を収集する Diode サーバーを構築します。以下のサイトを参考に実施

NetBox-SV 上で、以下を実施

# インストール先のディレクトリ作成と移動
mkdir /opt/diode
cd /opt/diode

# quickstart のスクリプトのダウンロードと準備
curl -sSfLo quickstart.sh https://raw.githubusercontent.com/netboxlabs/diode/release/diode-server/docker/scripts/quickstart.sh
chmod +x quickstart.sh

# jq ( JSON を扱うためのコマンドラインツール) をインストール
apt update && apt install -y jq

# NetBox サーバーのアドレスを指定してスクリプトを実行します
# サーバーのアドレスは、後で設定する NetBox 本体の docker-compose のサービス名の「netbox」
./quickstart.sh http://netbox:8080

次に、docker composeで起動するコンテナをネットワークnetbox-nwに所属させるようにdocker-compose.override.ymlを作成します

docker-compose.override.yml

services:
  ingress-nginx:
    networks:
      netbox-nw:   # 事前に作成したネットワーク

  diode-ingester:
    networks:
      netbox-nw:

  diode-reconciler:
    networks:
      netbox-nw:

  redis:
    networks:
      netbox-nw:
        aliases:
          - diode-redis   # NetBoxと重複するため、共有ネットワーク上で別名をつける

  postgres:
    networks:
      netbox-nw:
        aliases:
          - diode-postgres   # NetBoxと重複するため、共有ネットワーク上で別名をつける

  hydra:
    networks:
      netbox-nw:

  hydra-migrate:
    networks:
      netbox-nw:

  diode-auth:
    networks:
      netbox-nw:

  diode-auth-bootstrap:
    networks:
      netbox-nw:

networks:
  netbox-nw:
    external: true  # 事前に作成した既存ネットワークを使う

ここまで来たら、以下のコマンドでコンテナが起動します
(初回はコンテナのダウンロードからはじまります)

docker compose up -d

最後にnetbox-to-diodeのシークレットを抽出します。これはこの次のNetBoxのnetbox_diode_pluginのインストール時に必要となります。
（ NetBox 設定時にnetbox_to_diode_client_secretの値として利用します）

echo $(jq -r '.[] | select(.client_id == "netbox-to-diode") | .client_secret' /opt/diode/oauth2/client/client-credentials.json)

NetBox

NetBox を Doker で構築するためのファイルを GitHub からダウンロード

# /opt へ移動
cd /opt/

# NetBox Docker リポジトリの release ブランチをクローン
git clone -b release --depth=1 https://github.com/netbox-community/netbox-docker.git

# /opt/netbox-docker/ へ移動
cd netbox-docker/

コンテナ構築前に、NetBox Discovery に必要なブラグインの指定とパラメータ設定

netboxlabs-diode-netbox-plugin をインストールするように指定

plugin_requirements.txt

cat > plugin_requirements.txt <<'EOF'
netboxlabs-diode-netbox-plugin
EOF

プラグインで利用するパラメータの設定

• diode_target_overrideは、同じ Docker ネットワーク内で名前解決できるためingress-nginxとしています。別サーバーに Diode サーバーを構築する場合は Diode サーバーの IP アドレスにしてください
• netbox_to_diode_client_secretは、Diode サーバー構築時の最後に取得したnetbox-to-diodeのシークレットの値になります

plugins.py

cat <<'EOF' >> configuration/plugins.py
PLUGINS = ["netbox_diode_plugin"]

PLUGINS_CONFIG = {
    "netbox_diode_plugin": {
        # NetBox 側から Diode サーバーへ接続するための gRPC 接続先アドレス
        "diode_target_override": "grpc://ingress-nginx/diode",
        # プラグイン経由で適用された変更に関連付けられる NetBox のユーザー名
        "diode_username": "diode",
        # 'netbox_to_diode_client_secret' Diodeサーバー構築時に取得した値 
        "netbox_to_diode_client_secret": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
    }
}
EOF

NetBox 公式イメージをベースに、プラグインをビルド時に入れる Dockerfile を作成

Dockerfile-Plugins

cat > Dockerfile-Plugins <<'EOF'
FROM netboxcommunity/netbox:latest

# プラグイン本体をインストール
COPY ./plugin_requirements.txt /opt/netbox/
RUN /usr/local/bin/uv pip install -r /opt/netbox/plugin_requirements.txt
EOF

次に、docker composeで起動するコンテナを以下の内容を加えたdocker-compose.override.ymlを作成します

• ネットワークnetbox-nwに所属させる
• NetBox プラグインをビルド時に入れる
• NetBox の WEB-GUI のポート番号を 80 で待ち受けて、8080に変換してコンテナに渡す

docker-compose.override.yml

services:
  netbox:
    image: netbox:latest-plugins
    build:
      context: .
      dockerfile: Dockerfile-Plugins  # プラグインをビルド時に入れる
    ports:
      - "80:8080"   # WEB-UIで利用 
    networks:
      netbox-nw:

  netbox-worker:
    image: netbox:latest-plugins
    networks:
      netbox-nw:

  netbox-housekeeping:
    image: netbox:latest-plugins
    networks:
      netbox-nw:

  postgres:
    networks:
      netbox-nw:

  redis:
    networks:
      netbox-nw:

  redis-cache:
    networks:
      netbox-nw:
      
networks:
  netbox-nw:
    external: true  # 事前に作成した既存ネットワークを使う

ここまで来たら、以下のコマンドでコンテナが起動します
(初回はコンテナのダウンロードからはじまります)

# イメージをビルド
docker compose build --no-cache

# 起動する
docker compose up -d

自分の環境だとdocker compose up -dを初めてやった際にエラーでNetBoxがうまく起動しませんでしたが、一度docker compose downで停止させた後にもう一度docker compose up -dするとちゃんと起動しました

コンテナが起動したら、以下のコマンドで Netbox 用のユーザ作成します

docker compose exec netbox /opt/netbox/netbox/manage.py createsuperuser

次に、ブラウザからhttp://<サーバーのIP>/のURLにアクセスすると NetBox の WEB-UI を開くことができます
以下のように「Diode」というメニューが増えていれば OK です

最後に、この後に構築する Orb-Agent の認証情報を作成します
以下の画像のとおり作成してください

構築 ( NetBox-Orb-Agent )

orb-agent

次に別の NetBox-Orb-Agent サーバ上で orb-agent を構築していきます

NetBox-Orb-Agent上で、インストール先のディレクトリ作成と移動

# インストール先のディレクトリ作成と移動
mkdir /opt/orb-agent
cd /opt/orb-agent

次に環境変数をのファイルを.envとして作成
DIODE_CLIENT_IDとDIODE_CLIENT_SECRETは NetBox → Diode で発行した認証情報を入力

.env

cat > .env <<'EOF'
# NetBox → Diode で発行した認証情報
DIODE_CLIENT_ID=orb-agent01-XXXXXXXXXXXXX
DIODE_CLIENT_SECRET=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
EOF

次に、orb-agentで取得する条件が定義するagent.yamlを作ります
今回は、以下の内容にしています

• device_discoveryで機器情報を取得
• targetの部分は NetBox-SV の IP アドレスを入れて下さい
• 起動時に一回だけ取得
• policiesのscopeに取得する機器の種別やIP、ユーザ名・パスワードを記載
  • 今回は仮で、ユーザ名：admin、パスワード：admin123

agent.yaml

orb:
  config_manager:
    active: local
  backends:
    device_discovery: {}
    common:
      diode:
        target: grpc://<Netbox-SVのIPアドレス>:8080/diode   # Diode gRPC エンドポイント
        client_id: ${DIODE_CLIENT_ID}
        client_secret: ${DIODE_CLIENT_SECRET}
        agent_name: orb-agent01

  policies:
    device_discovery:
      network_device:
        config:
          #schedule: "*/1 * * * *"   # 定期的に実行する場合はscheduleで設定、scheduleがない場合は起動時の1回のみ取得
          timeout: 10
          defaults:
            description: discovered by device discovery
            tags: ["device-discovery"]  # 取得した値を反映するときにNetBox上で"device-discovery"のタグをつける
            # サイト：Home、ロケーション：Labo、ロール： Netwok Device に登録
            site: "Home"
            location: "Labo"
            role: "Netwok Device"
        scope:
          - driver: junos
            hostname: 10.99.0.101
            username: admin
            password: admin123
          - driver: eos
            hostname: 10.99.0.102
            username: admin
            password: admin123
            optional_args:
               transport : ssh # Arsista(eos)はデフォルトがhttpでのログインのため ssh に変更する
          # Ciscoの機器を取得したい場合は以下のように記載
          # - driver: ios
          #   hostname: 10.99.0.103
          #   username: admin
          #   password: admin123

最後にdocker-compose.ymlを設定、NetBox Discovery はデバイスから情報取得以外に、PING等でネットワーク内の生きてるIPを探す機能もあるので、あとでそれもできるように設定しています

docker-compose.yml

services:
  orb-agent:
    image: netboxlabs/orb-agent:latest
    container_name: orb-agent
    network_mode: host          # ICMP/TCP スキャン用に推奨
    env_file:
      - .env                    # DIODE_CLIENT_ID / DIODE_CLIENT_SECRET
    volumes:
      - ./agent.yaml:/opt/orb/agent.yaml:ro
    command: >
      run -c /opt/orb/agent.yaml
    cap_add:                    # ICMP を非特権で送るため
      - NET_RAW
      - NET_ADMIN

これで、起動すると 10.99.0.101 と 10.99.0.102 に対して情報を取得しにいきます
起動する前に以下の設定をしておきます

• NetBox の WEB-GUI 上で、サイト：Home、ロケーション：Labo を設定しておく
• 今回取得する vJunosSwitch-1 と vEOS-1 の設定

ネットワーク機器の設定は以下のとおりです

vJunosSwitch-1

vJunosSwitch-1

set version 24.4R1.9
set system host-name vJunosSwitch-1
set system root-authentication encrypted-password "$6$AC6nSlJw$zD2oMGKsCWksxinLTrzQPtZrBDKVE9n4vZlzb6/1iefrNGmgUyZdWJuKhP/Xs0cxz7FEwtU8SRNZL4Wgpi5In1"
set system login user admin uid 2000
set system login user admin class super-user
set system login user admin authentication encrypted-password "$6$RpWGw8S1$RStDkM2vj5h6qJRPkkVVKWHVMFtMR3HV.sOALE.ySzWY4dpaMj3eHJ8wPZOyMp8RcxXJpZwZmDVzzjT2xqaQb0"
set system services ssh
set system arp aging-timer 5
set system syslog file interactive-commands interactive-commands any
set system syslog file messages any notice
set system syslog file messages authorization info
set interfaces ge-0/0/0 description to_vEOS-1
set interfaces ge-0/0/0 unit 0 description to_vEOS-1
set interfaces ge-0/0/0 unit 0 family inet address 10.80.0.1/30
set interfaces fxp0 description MGMT
set interfaces fxp0 unit 0 family inet address 10.99.0.101/24

vEOS-1

vEOS

! Command: show running-config
! device: vEOS-1 (vEOS-lab, EOS-4.34.0F)
!
! boot system flash:/vEOS-lab.swi
!
no aaa root
!
username admin privilege 15 role network-admin secret sha512 $6$pqyamgFeXQ4uCARk$.RY6/eWrYF9WJOuEXLiCxxSSUIJQ5vOWnjy5.LtMhB5UbHCkrgtC8DNXuY.D1DFmprobIksOiLfJf1rwRA3DC.
!
no service interface inactive port-id allocation disabled
!
transceiver qsfp default-mode 4x10G
!
service routing protocols model multi-agent
!
no lldp run
!
hostname vEOS-1
!
spanning-tree mode mstp
no spanning-tree vlan-id 1-4094
!
system l1
   unsupported speed action error
   unsupported error-correction action error
!
vlan 80
!
interface Ethernet1
   description to_vJunosSwitch-1
   switchport access vlan 80
!
interface Ethernet2
!
interface Ethernet3
!
interface Ethernet4
!
interface Ethernet5
!
interface Ethernet6
!
interface Ethernet7
!
interface Ethernet8
!
interface Management1
   ip address 10.99.0.102/24
!
interface Vlan80
   description to_vJunosSwitch-1
   ip address 10.80.0.2/30
!
no ip routing
!
router multicast
   ipv4
      software-forwarding kernel
   !
   ipv6
      software-forwarding kernel
!
end

ネットワーク機器の情報や設定を自動収集する

NetBox-Orb-Agent サーバーの/opt/orb-agent上で、dockerでコンテナ起動すると、ネットワーク機器から情報取得し NetBox に自動登録をします

以下のコマンドを実行すること、起動し取得のログがでてきます

docker compose up && docker compose down

取得動作が終わったらCtrl + C で止めることができます

この後に NetBox の WEB-GUI を確認すると、2台のネットワークデバイスが登録されていることがわかります
自動登録した一部の画面キャプチャを貼り付けます
デバイス情報だけでなく、IPアドレスとIFに紐づけなど自動で設定されます

▼ Device

▼ Device Type

▼ Manufacturers

▼ Interfaces

▼ IP Addresses　

最後に

今回は、Netbox Discovery を使ってネットワーク機器の情報を登録してみました

インターフェースと IP アドレスの紐付けなど、面倒な作業をすべて自動で行ってくれるため、既存の稼働中ネットワークに NetBox を導入する際、既存機器の情報登録に非常に役立つと感じました。

Netbox Discovery ネットワーク機器の情報の取得以外にも特定セグメントをPING監視して NetBox に登録のないIPアドレスを自動登録することもできますので参考に設定ファイルを記載しておきます

agent.yaml

agent.yaml

orb:
  config_manager:
    active: local
  backends:
    # device_discovery: {}
    network_discovery: {} # network_discovery を追加
    common:
      diode:
        target: grpc://<NetBox-SVのIPアドレス>:8080/diode   # Diode gRPC エンドポイント
        client_id: ${DIODE_CLIENT_ID}
        client_secret: ${DIODE_CLIENT_SECRET}
        agent_name: orb-agent01

  policies:
    network_discovery:
      discovery_1:
        config:
          schedule: "*/5 * * * *"   # 5分に一回起動する
          timeout: 5
          defaults:
            description: IP discovered by network discovery
            tags: ["network_discovery"]  # 取得した値を反映するときにNetBox上で"network_discovery"のタグをつける
        scope:
          targets:
            - 10.10.0.0/24        # 監視したいネットワーク
          ping_scan: true
          exclude_ports: [80, 443]  # ping_scan: true にしても 80と443をポートスキャンしてしまうので明示的に除外

    # device_discovery:
    #   network_device:
    #     config:
    #       #schedule: "*/1 * * * *"   # 定期的に実行する場合はscheduleで設定、scheduleがない場合は起動時の1回のみ取得
    #       timeout: 10
    #       defaults:
    #         description: discovered by device discovery
    #         tags: ["device-discovery"]  # 取得した値を反映するときにNetBox上で"device-discovery"のタグをつける
    #         # サイト：Home、ロケーション：Labo、ロール： Netwok Device に登録
    #         site: "Home"
    #         location: "Labo"
    #         role: "Netwok Device"
    #     scope:
    #       - driver: junos
    #         hostname: 10.99.0.101
    #         username: admin
    #         password: admin123
    #       - driver: eos
    #         hostname: 10.99.0.102
    #         username: admin
    #         password: admin123
    #         optional_args:
    #            transport : ssh # Arsista(eos)はデフォルトがhttpでのログインのため ssh に変更する
    #       # Ciscoの機器を取得したい場合は以下のように記載
    #       # - driver: ios
    #       #   hostname: 10.99.0.103
    #       #   username: admin
    #       #   password: admin123