インストールとアップグレード

Diagram showing routerd install and upgrade from release archive download and install.sh through first router.yaml validation, plan, serve mode, preserved config and state, and uninstall

ルーターホストへはリリースアーカイブから導入します。アーカイブには、実行ファイル、サービステンプレート、設定例、インストーラーが含まれます。ルーターホストに Go や Makefile は要りません。

クイックインストール

GitHub Releases から、OS とアーキテクチャーに合うアーカイブを取得します。

Linux amd64:

curl -LO https://github.com/imksoo/routerd/releases/latest/download/routerd-linux-amd64.tar.gz
curl -LO https://github.com/imksoo/routerd/releases/latest/download/routerd-linux-amd64.tar.gz.sha256
sha256sum -c routerd-linux-amd64.tar.gz.sha256
tar -xzf routerd-linux-amd64.tar.gz
sudo ./install.sh

Linux arm64 では linux-arm64 アーカイブを使います。

FreeBSD amd64:

fetch https://github.com/imksoo/routerd/releases/latest/download/routerd-freebsd-amd64.tar.gz
fetch https://github.com/imksoo/routerd/releases/latest/download/routerd-freebsd-amd64.tar.gz.sha256
cat routerd-freebsd-amd64.tar.gz.sha256
sha256 routerd-freebsd-amd64.tar.gz
tar -xzf routerd-freebsd-amd64.tar.gz
sudo ./install.sh

FreeBSD arm64 では freebsd-arm64 アーカイブを使います。最新リリースには routerd-vYYYYMMDD.HHmm-linux-amd64.tar.gz のような版番号付きアーカイブもあります。特定の版に固定する場合は、版番号付きアーカイブを使います。

Linux 用アーカイブには、CGO_ENABLED=0 で静的リンクした routerd バイナリを含めます。そのため、配置先ホストの glibc 版には依存しません。 dnsmasq、nft、ip、conntrack、tcpdump などの実行時ツールは、引き続き install.sh が導入または確認します。

native nDPI によるアプリケーション識別が必要なホストでは、対応する routerd-ndpi-agent-libndpi-linux-amd64.tar.gz も取得し、通常のアーカイブと同じインストール処理の中で明示的に適用します。

curl -LO https://github.com/imksoo/routerd/releases/latest/download/routerd-ndpi-agent-libndpi-linux-amd64.tar.gz
curl -LO https://github.com/imksoo/routerd/releases/latest/download/routerd-ndpi-agent-libndpi-linux-amd64.tar.gz.sha256
sha256sum -c routerd-ndpi-agent-libndpi-linux-amd64.tar.gz.sha256
sudo ./install.sh --with-ndpi \
  --with-ndpi-archive ./routerd-ndpi-agent-libndpi-linux-amd64.tar.gz

--with-ndpi を付けた場合、導入後の routerd-ndpi-agent が libndpiLoaded: true を返さなければ処理は失敗します。これにより、static なフォールバックエージェントが native nDPI の要件を黙って満たしたことにはなりません。

install.sh は新規導入かアップグレードかを自動で判定します。実行ファイルを /usr/local/sbin に配置し、サービステンプレートを導入します。また、/usr/local/etc/routerd/router.yaml.sample を作成します。既存の /usr/local/etc/routerd/router.yaml は上書きしません。 systemd ホストでは、インストーラーがローカルソケットアクセス用の routerd グループを作成します。sudo usermod -aG routerd <user> で運用者を追加すれば、 routerctl status などのローカル制御ソケット操作を sudo なしで実行できます。

BGP を動かしているルーターのアップグレード

routerd-bgp は長寿命のデーモンで、BGP セッションを保持します。再起動するとセッションが切断され、ピアは保留タイマーが満了するまで古い経路を保持するため、その間 ECMP の幅が縮小します。 systemd ホストでは、install.sh がアップグレード前の削除済みバイナリをまだ実行中のアクティブな routerd ヘルパーサービス (routerd-bgp や routerd-dns-resolver など) を自動でリフレッシュします。これにより、アップグレード後のホストが /proc/*/exe の下に古い実行ファイルを抱え続けることを防ぎます。

インストーラーがヘルパーを再起動した後は、BGP の再収束が起きます。再収束中に routerd-bgp を再度再起動しないでください。短時間に 2 回再起動すると、ピアが古い経路を保持し続け、ECMP が崩壊します。 Graceful Restart が保護できるのは 1 回の再起動だけです。判断は再収束を待ってから行います (BGP の保留タイマーと Graceful Restart の stale-path タイマーにより、最大約 3--6 分かかります)。合格条件は、すべてのピアが Established に戻ること、影響するプレフィックスで ECMP 幅が回復すること、エンドツーエンドの疎通 (例: ECMP 経路を通る HTTP 200) が成功することです。

この間、1 つのピアが IDLE のまま Closed an accepted connection を繰り返しログに出すことがあります。これは、前のセッションをまだ保持しているピアが保留タイマーの満了を待っている状態です。追加の再起動はせず、待ってください。タイマー満了後にピアは自動で接続を確立し、 ECMP も回復します。

root 以外の運用者によるローカル制御ソケットアクセス

読み取り専用の状態ソケット (/run/routerd/routerd-status.sock) を使えば、 root 以外の運用者も sudo なしで routerctl status を実行できます。 routerd グループが存在する場合、routerd はこのソケットを root:routerd、モード 0o660 で作成します。 Unix ソケットへの接続には書き込み権限が必要なので、グループのメンバーは読み書き可能です。このグループ所有権は、routerd がソケットを作成する際に自身で設定するため、サービスユニットの Group= 設定には依存しません。 routerd グループが存在しない場合は、誰もロックアウトされないよう、状態ソケットを全アクセス可 (0o666) にフォールバックします。

読み書き用の制御ソケット (/run/routerd/routerd.sock、routerctl apply / delete で使用) は、root 所有の 0o660 のままです。ルーターへの変更操作には、引き続き root / sudo が必要です。

sudo なしで routerctl status を使えるようにする手順:

sudo usermod -aG routerd <user> (インストーラーがグループを作成済み)。
グループメンバーシップは新しいログインセッションにのみ適用されます。反映前に再ログイン (または新しい SSH セッションを開く / newgrp routerd を実行) してください。フルの再ログインなしで現在のシェルでグループを使うには、コマンドをラップします: sg routerd -c 'routerctl status'。

ls -l /run/routerd/routerd-status.sock で確認します (期待値: srw-rw---- root routerd)。id <user> でグループ一覧に routerd が含まれることを確認します。グループに入っていないユーザーが拒否されるのは、意図した堅牢化であり、後退ではありません。サービスユニットの変更は不要です。

ライブ ISO で試す

リリースページでは、Ubuntu ベースの起動可能なライブ ISO も公開します。

curl -LO https://github.com/imksoo/routerd/releases/latest/download/routerd-live.iso
curl -LO https://github.com/imksoo/routerd/releases/latest/download/routerd-live.iso.sha256
sha256sum -c routerd-live.iso.sha256

ISO を Proxmox VE のテスト VM に接続して起動します。コンソールには routerd の初期設定手順が表示されます。 root でログインすれば、同じ install.sh configure ウィザードを起動できます。 ISO はデモや短時間の試用に向いています。永続的なルーターとして使う場合は、リリースアーカイブからディスクへ導入します。

ライブ ISO は、ビデオコンソールとシリアルコンソールの両方を有効にします。仮想マシン (KVM / Proxmox など) では、ライブ起動時に qemu-guest-agent サービスが利用可能であれば自動起動を試みます。 sshd は仮想化環境での運用者アクセス用に同梱していますが、ライブ ISO ではデフォルトで停止しています。 Proxmox VE では、シリアルソケットを追加し、qm terminal で接続します。

qm create 200 \
  --name routerd-live-demo \
  --memory 1536 \
  --cores 2 \
  --ostype l26 \
  --serial0 socket \
  --vga serial0 \
  --boot order=ide2 \
  --ide2 local:iso/routerd-live.iso,media=cdrom \
  --net0 virtio,bridge=vmbr0 \
  --net1 virtio,bridge=vmbr490
qm start 200
qm terminal 200

DHCP や RA を試す場合は、net1 に隔離した LAN ブリッジを使います。シリアルコンソールは 115200 8N1 です。ウィザードはプレーンテキストで表示します。そのため、qm terminal、フレームバッファーコンソール、最小構成の端末のいずれでも同じように動きます。

ライブ ISO には 2 つの動作があります。

一時デモモード: USB ストレージを選びません。設定とログは RAM 上に置かれ、再起動で消えます。
永続ルーターモード: ウィザードで USB パーティションを選びます。ウィザードが router.yaml を USB デバイスへ保存します。次回の起動時には、ISO が USB デバイスをマウントし、設定を復元して自動的に反映します。

永続モードでは、USB パーティションに ROUTERD というラベルを付けます。リムーバブルデバイスが複数ある場合は、カーネル引数に routerd.usb=/dev/sdX1 を指定できます。ヘルパーは blkid で ext4、vfat、exfat を判別します。既定では async,noatime でマウントします。同期書き込みを明示したい場合にだけ、routerd.usb_mount=sync を指定します。

ログは /run/routerd/logs の tmpfs に一時保存します。ウィザードでは、1 日 1 回の書き出しジョブを有効にできます。このジョブは、設定、状態スナップショット、圧縮したログアーカイブを USB デバイスへコピーします。 tmpfs のログ上限は既定で 100 MiB です。上限を超えた場合は、古いログファイルから順に削除します。

USB を安全に取り外す場合は、次を実行します。

/usr/share/routerd/live-persistence.sh flush
/usr/share/routerd/live-persistence.sh umount

配置先、マウントオプションは Operations → USB 永続化を参照してください。

routerd-live-vYYYYMMDD.HHmm.iso のような版番号付き ISO も公開します。

実行時の依存パッケージ

既定では、install.sh が既知の OS パッケージを導入します。一覧だけを確認するには、次を実行します。

./install.sh --list-deps

別の仕組みでパッケージを管理する場合は、自動導入を止めます。

sudo ./install.sh --no-install-deps

依存パッケージだけを導入することもできます。

sudo ./install.sh --deps-only

Tailscale の導入は任意です。導入する場合は --with-tailscale を付けます。

sudo ./install.sh --with-tailscale

Debian / Ubuntu

インストーラーは apt-get を使い、次を導入します。

ca-certificates curl dnsmasq-base nftables wireguard-tools chrony bind9-dnsutils tcpdump cron jq ppp pppoe conntrack iproute2 iputils-ping iputils-tracepath net-tools kmod radvd strongswan-swanctl iptables keepalived openssh-server

Fedora 系

インストーラーは dnf を使い、次を導入します。

ca-certificates curl dnsmasq nftables wireguard-tools chrony bind-utils tcpdump cronie jq ppp rp-pppoe conntrack-tools iproute iputils traceroute kmod radvd strongswan iptables keepalived openssh-server

Arch 系

インストーラーは pacman を使い、次を導入します。

ca-certificates curl dnsmasq nftables wireguard-tools chrony bind tcpdump cronie jq ppp rp-pppoe conntrack-tools iproute2 iputils traceroute kmod radvd strongswan iptables keepalived openssh

FreeBSD

インストーラーは pkg を使い、次を導入します。

ca_root_nss curl dnsmasq wireguard-tools mpd5 bind-tools tcpdump jq chrony strongswan

FreeBSD の pf、ifconfig、route、sysctl、service、sysrc、cron、 netstat、sockstat、ping、traceroute は基本システムの機能です。これらはパッケージとして導入せず、コマンドの存在だけを確認します。

アップグレード

新しいアーカイブを展開し、同じインストーラーを実行します。

tar -xzf routerd-linux-amd64.tar.gz
sudo ./install.sh

/usr/local/sbin/routerd が存在する場合、インストーラーはアップグレードモードに切り替わります。このとき、古い routerd --version と新しい routerd --version を表示します。実行ファイルとサービステンプレートを置き換える一方で、設定と状態は保持します。 routerd サービスが起動中であれば再起動します。 systemd ホストでは、再起動した routerd.service の状態ソケットを待ち、 routerd が管理するユニットファイルの更新が落ち着いてから、更新が必要な routerd ヘルパーサービスだけを再起動します。再起動するのは、削除済みのアップグレード前バイナリを実行している場合、またはヘルパーのプロセス起動後にユニットファイルが更新された場合だけです。 /etc/systemd/system/routerd.service が routerd の設定で管理されている場合は、アーカイブのテンプレートで上書きせず、そのユニットを保持します。

置き換えるファイルは *.backup.YYYYMMDDHHMMSS に退避します。途中で失敗した場合は、一時バックアップから復元します。

routerd 自身が routerd.service を、生成されるサービス成果物のリソースとして管理している場合、ユニットファイルの変更は慎重に扱います。適用の途中で自分自身を直接再起動するのではなく、systemd-run で少し遅らせた自己再起動を予約します。 VRRP または ingress サービスのリソースを同じ設定に含む場合は、生成される routerd.service に、keepalived 用の書き込み可能なパスと capability を自動で追加します。 BGP は長寿命の routerd-bgp デーモンをローカルの gRPC Unix ソケットで制御するため、 FRR group や FRR の実行時ディレクトリは要りません。

よく使うオプション:

sudo ./install.sh --no-restart
sudo ./install.sh --dry-run
sudo ./install.sh --verbose
sudo ./install.sh --no-config-update

配置先

項目	Linux	FreeBSD
設定	`/usr/local/etc/routerd/router.yaml`	`/usr/local/etc/routerd/router.yaml`
設定例	`/usr/local/etc/routerd/router.yaml.sample`	`/usr/local/etc/routerd/router.yaml.sample`
実行ファイル	`/usr/local/sbin`	`/usr/local/sbin`
サービステンプレート	`/etc/systemd/system/routerd.service`	`/usr/local/etc/rc.d/routerd`
実行時ソケット	`/run/routerd`	`/var/run/routerd`
永続状態	`/var/lib/routerd`	`/var/db/routerd`

インストーラーは次の状態を削除しません。

/usr/local/etc/routerd/router.yaml
/var/lib/routerd
/var/db/routerd
/run/routerd
/var/run/routerd
/var/log/otelcol

最初の設定

最初の試用では、組み込みの初期設定ウィザードを使えます。

sudo ./install.sh configure

ウィザードは、WAN インターフェース、LAN インターフェース、LAN アドレス、 LAN 向けサービス、管理経路の置き場所、任意の USB 永続化を順に確認します。生成した候補は /usr/local/etc/routerd/router.yaml.configure に保存します。既存の設定がある場合は差分を表示します。確認後、/usr/local/etc/routerd/router.yaml へ導入します。その後、routerctl validate、routerctl plan、routerctl apply を実行します。

自動化する場合は、環境変数で値を渡して質問を省略できます。

sudo ROUTERD_WAN_INTERFACE=ens18 \
  ROUTERD_LAN_INTERFACE=ens19 \
  ROUTERD_LAN_ADDRESS=192.168.10.1/24 \
  ROUTERD_LAN_CIDR=192.168.10.0/24 \
  ROUTERD_MGMT_MODE=lan \
  ROUTERD_ENABLE_USB_PERSISTENCE=no \
  ./install.sh configure --non-interactive --yes

ライブ ISO で USB 永続化を使う場合は、次の値を指定します。

sudo ROUTERD_ENABLE_USB_PERSISTENCE=yes \
  ROUTERD_USB_DEVICE=/dev/sdb1 \
  ROUTERD_USB_FLUSH=yes \
  ROUTERD_LOG_TMPFS_LIMIT=100M \
  ./install.sh configure --non-interactive --yes

YAML ファイルの生成だけを行う場合は、--no-apply を使います。

sudo ./install.sh configure --no-apply

手動で設定することもできます。設定例をコピーし、インターフェース名などを編集してください。

sudo install -d -m 0755 /usr/local/etc/routerd
sudo install -m 0600 /usr/local/etc/routerd/router.yaml.sample /usr/local/etc/routerd/router.yaml
sudo vi /usr/local/etc/routerd/router.yaml

検証し、計画を確認します。

routerctl validate -f /usr/local/etc/routerd/router.yaml --replace
routerctl plan -f /usr/local/etc/routerd/router.yaml --replace

管理経路が安全だと確認してから反映します。

sudo routerctl apply -f /usr/local/etc/routerd/router.yaml --replace

一度だけの反映が正常に終われば、サービスを起動します。

sudo systemctl enable --now routerd.service

FreeBSD では次のようにします。

sudo sysrc routerd_enable=YES
sudo service routerd start

アンインストール

リリースアーカイブには uninstall.sh も含まれます。既定では、実行ファイル、サービステンプレート、実行時ファイルを削除し、設定と状態は残します。

sudo ./uninstall.sh --yes

削除範囲を広げる場合は、明示的に指定します。

sudo ./uninstall.sh --yes --purge-config
sudo ./uninstall.sh --yes --purge-state
sudo ./uninstall.sh --yes --all

--dry-run で削除内容だけ確認できます。

開発者向けワークフロー

Makefile は開発用です。テスト、ビルド、スキーマ生成、設定例の検証、Web サイトのビルド、リリースアーカイブの作成に使います。

make test
make check-schema
make validate-example
make website-build
make dist ROUTERD_OS=linux GOARCH=amd64 VERSION="$(git describe --tags --abbrev=0)"

利用者向けの導入経路としては Makefile を使いません。標準の配置方法は、リリースアーカイブと install.sh です。

クイックインストール​

BGP を動かしているルーターのアップグレード​

root 以外の運用者によるローカル制御ソケットアクセス​

ライブ ISO で試す​

実行時の依存パッケージ​

Debian / Ubuntu​

Fedora 系​

Arch 系​

FreeBSD​

アップグレード​

配置先​

最初の設定​

アンインストール​

開発者向けワークフロー​