status と doctor
ironflock status は、マシン上に IronFlock の何があり、それが動作しているかを表示します。ironflock doctor は、マシンがデバイスエージェントを実行できるか、エージェントが通信するホストに到達できるかをチェックします。マシンを接続する前や、デバイスがオンラインにならないときに使います。
どちらのコマンドも、何も変更せず、何も質問しません。Linux と macOS で root なしで動作し、root で実行するとより多くを読み取ります。--host を付けると別のマシン上で実行され、複数のマシンで同時に実行することもできます(SSH 経由のリモートマシン)。その場合、ログインユーザーが root のとき、またはパスワードも端末も必要とせずに sudo を使えるときは、root で実行されます。そうでない場合は、質問せずにログインユーザーとして実行され、ヒントに --host root@machine を付けたコマンドが示されます。
ironflock status
このマシンのデバイスエージェント、アプライアンス、オペレーティングシステムについて、何がインストールされているか、そのバージョン、サービスが動作しているか、デバイスとそのプロジェクト、エージェントの最後の自己更新を表示します。アプライアンスとは、現場のマシン上で動作する IronFlock システム一式です(IronFlock アプライアンス)。アプライアンスについては、UI のアドレス、ライセンス、サービスの健全性、待機中の更新も表示します(アプライアンスのコマンド)。IronFlockOS では、ルートスロットと、対処が必要な事項も表示します。
ironflock status [flags]動作環境: Linux。macOS ではシステムと、何もインストールされていないことを表示します。root: 不要。一部の情報には必要です。質問: なし。
このコマンドに固有のフラグはありません。グローバルフラグを受け付けます(グローバルフラグ)。
root でない場合、一部の情報は読み取れません。エージェントの .flock は root しか読めないため、デバイスとそのプロジェクトは読み取れません。アプライアンスでは、そのフォルダー /opt/ironflock が root のものであるため、バージョン、アプライアンスの URL、ライセンス、その更新、エージェントの更新も読み取れません。アプライアンスのサービスの健全性には、root またはグループ docker が必要です。これらは unknown (needs root) と表示され、JSON フィールド needs_root に一覧されます。sudo ironflock status を使えば読み取れます。
# このマシンにあるものを、ログインユーザーとして読み取る
ironflock status
# すべてを JSON で
sudo ironflock status --json
# SSH 経由で別のマシンの状態を表示する
ironflock --host pi@device-17 statusテキスト出力
$ ironflock status
Agent: installed in /opt/ironflock/device-agent
Version: 1.6.9
Service: running (ironflock-device-agent.service)
Connection: unknown (this agent does not report it)
Device: unknown (needs root)
Swarm: unknown (needs root)
Update: none pending
Appliance: not installed
System: Debian GNU/Linux 12 (bookworm)
Run 'sudo ironflock status' to read what needs root.Swarm はデバイスのプロジェクトです。動作中のエージェントでは、Connection は unknown です。これまでにリリースされたエージェントは、マシン上で接続状態を報告しないためです。
IronFlockOS の場合
システムの行には、イメージとその 2 つのルートスロットが表示されます(ルートスロットとデータパーティション):
System: IronFlockOS 0.13.0 (amd64-efi, base)
Image: ironflockos-amd64-efi-base (build 20261105T120000Z-g1a2b3c4)
Slot A: inactive, good
Slot B: booted, good, 0.13.0 installed 2026-11-05T14:00:00Z
Next boot: slot BIronFlockOS デバイスのエージェントは、デバイスが登録されたときにイメージがセットアップしたもので、/data 上の /opt/ironflock/device-agent にあり、ほかのシステムと同じように表示されます。まだ登録されていないデバイスにはエージェントがありません。エージェントはイメージに含まれており、行にはデバイスの登録方法が示されます(下の 1 行目)。今回の起動時に /data をマウントできなかった場合は、登録済みかどうかにかかわらずエージェントのフォルダーも見えないため、行にはその旨が示されます(2 行目):
Agent: not enrolled yet: the device enrolls with a .flock on its IRONFLOCKOS partition at its next start, or now with 'sudo ironflock agent configure -c <file>'
Agent: not to be seen: /data, which holds the agent and its .flock, could not be mounted (below); a .flock on the IRONFLOCKOS partition enrolls the device at its next start for as long as /data is missingシステムの下には、IronFlockOS が伝えることがある場合にだけ、それぞれ 1 行が表示されます:
| 行 | 表示される条件 |
|---|---|
Last reset: | 最後のファクトリーリセットが失敗した、または断念された。記録の意味は os reset で説明しています |
Reset hold: | リセットが未完了である(wait:前の所有者のデータが /data にある可能性がある間は、IRONFLOCKOS パーティション上の .flock または proxy.conf は取り込まれない。copy:リセットが消去を開始した)、またはリセットを断念し、リセットとともに置かれた .flock と proxy.conf を削除できなかった。これらは使われないまま残る(gave-up) |
/data: | /data をマウントできなかった。デバイスはルートスロット自身のフォルダーで動作し、Docker とアプリは動作しない |
/apps: | /apps がデータパーティションのフォルダーではない。アプリは動作するが、次回の OS 更新でデータを失う |
Last reset: gave up after 3 attempts at 2026-11-11T09:00:00Z: the data partition is not the partition named data on the disk of the root slot; /data holds the old data; left of the old owner: the data partition, the booted root slot, the other root slot
Reset hold: wait: a reset is open; a .flock or proxy.conf on the IRONFLOCKOS partition is not taken while the old owner's data may be on /data
/data: NOT MOUNTED: the device runs on the root slot's own folders; Docker and the apps do not run, and what is written now is lost with the next update
/apps: not the data partition's folder: the apps run, but lose their data at the next OS updateリセットの試行が失敗した場合、ホールドが wait または copy の間は attempt 1 of 3 failed at <time>: <reason>; /data holds the old data; the next start tries again と表示され、ホールドがない場合は no request is open now と表示されます。root でない場合、表示されるリセットの記録は、実行中のスロットにあるそのコピーです。IRONFLOCKOS パーティションは root しか読めないためです。
最後の os install
EFI 変数を持つすべての Linux では、最後の ironflock os install が IronFlock の EFI 変数 IronFlockInstall に記録した内容がある場合、それを OS install: の行に表示します。この変数はすべてのユーザーが読めます。読み取れない場合、またはマシンに EFI 変数がない場合は、行も警告も表示されません。値を解析できない場合は警告になります。
System: Debian GNU/Linux 13 (trixie)
OS install: 'ironflock os install' stopped at 2026-11-11T10:00:00Z before it wrote the disk: the disk /dev/sda is not the plan's: its size changed from 64.0 GB to 32.0 GB; nothing was changed, and this system runs as before| ステージ | 行の内容 |
|---|---|
stopped | ディスクに書き込む前に停止したこと、その理由、何も変更されていないこと |
handed-over | 古いシステム上では、再起動時にインストーラーが実行されず、何も変更されていないこと。IronFlockOS 上では、このシステムを書き込んだが、インストールがどう終わったかを記録できなかったこと |
writing | ディスクへの書き込みを開始し、完了を記録しなかったこと |
done | IronFlockOS 上では、このシステムが os install でインストールされたこと。それ以外では、マシンのディスクに IronFlockOS を書き込み、実行中のシステムは別のものであること |
failed | ディスクに書き込んだが、書き込んだ内容を読み戻しで検証できなかったこと、その理由 |
この記録が削除されることはありません。この行は、次の os install が記録を置き換えるまで残ります。変換されたデバイスでは、システムがこの方法でインストールされたことを示す記録として残ります。
JSON の結果
--json は同じ内容を 1 つの JSON オブジェクトとして出力します。ここでは複数行で示していますが、コマンドは 1 行で出力します。
{
"agent": {
"installed": true,
"layout": "current",
"dir": "/opt/ironflock/device-agent",
"version": "1.6.9",
"service": {"unit": "ironflock-device-agent.service", "state": "running"},
"connection": "unknown",
"device": "demo-device",
"swarm": "demo_swarm",
"update": {"state": "none"}
},
"appliance": {"installed": false},
"os": {"name": "Debian GNU/Linux 12 (bookworm)", "id": "debian", "version": "12", "ironflockos": false},
"needs_root": []
}読み取れない情報は unknown です。root 以外が理由の場合は、stderr の警告がその理由を示します。
| フィールド | 値 |
|---|---|
agent.installed | エージェントがインストールされている場合は true。その場合に限り、layout から update までのフィールドがあります。IronFlockOS では、false はデバイスがまだ登録されていないことを意味します |
agent.unfinished_install | true:エージェントはないが、以前のインストールがエージェントの段階に達する前に止まった。agent install はまずそれを元に戻します。それ以外の場合、このフィールドはありません |
agent.layout | current(/opt/ironflock/device-agent)、legacy(以前のインストーラーによる /opt/reagent)、migrating(エージェントが旧レイアウトを現在のレイアウトに移行している最中) |
agent.dir | エージェントのフォルダー |
agent.version | エージェントのバイナリが -version で示すバージョン |
agent.service | unit と state:running、starting、stopping、stopped、failed、not_found(systemd がユニットを知らない)、unknown |
agent.connection | エージェントが動作していない場合は disconnected。動作中のエージェントの接続状態は unknown です。connected は、接続状態を報告するエージェントでのみ得られます |
agent.device, agent.swarm | .flock から読み取った、デバイスの名前とそのプロジェクト。.flock のそれ以外の内容は読み取りません |
agent.update | 最後の自己更新。state:none(進行中のものも失敗したものもない)、activating、probation(新しいバージョンが動作しており、接続して正常であることを示す必要がある)、rolled_back(失敗して以前のバージョンが再び動作しており、新しいバージョンは後で再試行される)、blocked(最終的に失敗した。エージェントはより新しいリリースを待つ)、unknown。version、previous_version、reason、updated_at が付きます |
appliance.installed | IronFlock アプライアンスがインストールされている(そのユニット ironflock.service がある)場合は true。その場合、dir、version、channel、url、license、service、health、update があります |
appliance.data_left | アプライアンスがインストールされておらず、/opt/ironflock にそのデータが残っている場合のみ。--purge なしの appliance remove や、途中で止まったインストールが残したもので、そのフォルダーを示します |
appliance.version, appliance.channel | アプライアンスのフォルダーにあるファイル VERSION と CHANNEL |
appliance.url | UI のアドレス:その .env の HOME_URL。シークレットを含む .env のほかの部分は読み取りません |
appliance.license | license.env にライセンスキーがある場合は present、ない場合は missing、その LICENSE_KEY がライセンスキー(UUID)でない場合は invalid。アプライアンスのどのコマンドもそのようなキーを無視し、テキストにもその旨が示されます。キーが表示されることはありません |
appliance.service | ironflock.service。状態はエージェントのものと同じです。running は、ユニットがコンテナを起動したことを意味し、各コンテナが正常であることは意味しません |
appliance.health | docker ps から見たサービスの状態:state は healthy(各サービスが動作してヘルスチェックに合格している、ヘルスチェックがない、または 1 回実行されて 0 で終了した)、starting(ヘルスチェックが保留中)、unhealthy、down(コンテナがない)、unknown。services はコンテナの数。problems は正常でない各サービスと、その state(unhealthy、starting、restarting、exit_code 付きの exited など) |
appliance.update | 待機中の更新。UI とその再試行タイマーが書き込むステータスファイルから読み取ります:state は none(要求されていない、または最後の更新が完了した)、running、failed(再試行タイマーが再び試みる)、unknown。version、since、message 付き。cut_short(root のみ)は、途中で中断された更新がファイルを残したリリースを示します。次の更新は、まずそれを元に戻します。リリースの照会は行いません |
appliance.ironflock | アプライアンスのユニットが起動のたびに実行する ironflock(path、/usr/local/bin/ironflock)が、最後にアプライアンスをインストールまたは更新したもの(installed)と比べて missing または older(state。version はそれが示すバージョン)の場合のみ。root のみで、ironflock がインストールしたアプライアンスに限ります。その場合、テキストには何をインストールすべきかを示す ironflock: の行があります |
os.name, os.id, os.version | /etc/os-release の PRETTY_NAME、ID、VERSION_ID。Mac では macOS 15.5、macos、15.5 |
os.ironflockos | IronFlockOS では true。その場合、os.version はその IMAGE_VERSION で、以下のフィールドが続きます |
os.image, os.build | イメージの IMAGE_ID と BUILD_ID |
os.booted_slot, os.primary_slot | システムが動作しているスロットと、次回の起動で使われるスロット:A または B |
os.slots | ルートスロット:name(A)、rauc_slot(rootfs.0)、state(booted、active、inactive)、boot_status(good、bad)、そこに更新がインストールしたリリースの version と installed_at(イメージで書き込まれたスロットにはありません)。スロットを読み取れない場合、このフィールドはありません |
os.last_reset | 最後のファクトリーリセットの記録。failed または gave-up の場合のみ:result、time、version、attempt、attempts_max、reason、data(old、new、none:現在 /data にあるもの)、gave-up の場合は left(data、booted-slot、other-slot のうち、前の所有者のものがまだ残っている可能性があるもの) |
os.reset_hold | wait、copy、gave-up。リセットのホールドがある間のみ(上の表を参照) |
os.data_missing | true。/data をマウントできなかった場合のみ |
os.install | 最後の os install が記録した内容。EFI 変数を持つすべての Linux で、記録があり読み取れる場合のみ:stage、time(RFC 3339、UTC)、reason(stopped と failed の場合) |
os.apps_not_persistent | true。/apps がデータパーティションのフォルダーでない場合のみ |
needs_root | コマンドが root で実行されなかったために unknown となったフィールド。たとえば agent.device と agent.swarm です。読み取れなかったものがなければ空です |
終了コード
概要を出力できた場合、終了コードは常に 0 です。停止したエージェント、ロールバックされた更新、bad のスロットを表示する場合も同じです。status は報告するだけで判定はしないため、スクリプトがフィールドを読み取って判断します。概要を出力できない場合は 1 です。そのほかの終了コードについては、終了コード を参照してください。
ironflock doctor
このマシンがデバイスエージェントを実行できるか、エージェントが通信するホストに到達できるかをチェックします。対象は、システム、systemd、Docker、ディスクの空き容量、時刻、DNS、プロキシ、ダウンロードサーバー、デバイスの .flock に記載されたホストです。
ironflock doctor [flags]動作環境: Linux と macOS。root: 不要。root なしでは確認できないチェックは skipped となり、その旨を示します。質問: なし。
| フラグ | 意味 |
|---|---|
-c, --config <file> | ホストをチェックする対象となる、デバイスの .flock ファイル(既定値:インストール済みのエージェントのもの) |
agent install は、何かを変更する前に、privileges と docker を除くこれらのチェックを実行し、system、systemd、disk_space、download_tree のいずれかが失敗すると停止します。
# このマシンをログインユーザーとしてチェックする
ironflock doctor
# すべてを root でチェックし、JSON で出力する
sudo ironflock doctor --json
# .flock をインストールする前に、そのホストをチェックする
ironflock doctor -c device.flock結果
各チェックには、ID、結果、1 行の所見があります。ok 以外の結果には、どうすればよいかを示すヒントが付きます。
| 結果 | 意味 |
|---|---|
ok | 対処は不要 |
warning | 動作する可能性はあるが、十分には動作しない |
failed | マシンの現在の状態では、エージェントをインストールできない、または動作しない |
skipped | チェックが確認できなかった。所見にその理由が示される |
チェック
チェックは、表示される順に並んでいます。チェックの ID は変わらず、新しいチェックには新しい ID が付きます。
| ID | 確認する内容 | ok でない場合 |
|---|---|---|
privileges | コマンドが root で実行されているか | root なしで確認できなかったチェックがある場合は warning。所見にそれらのチェックが示されます。sudo ironflock doctor を実行してください |
system | Linux で、Debian または Ubuntu ベース(インストールはパッケージを apt から取得します)か IronFlockOS であること、エージェントのダウンロード対象となるアーキテクチャ | ほかのシステムでは failed、apt を持つほかの Linux では warning。failed の場合、agent install は停止します |
systemd | systemd がシステムを動かしている(/run/systemd/system がある) | systemd がシステムを動かしていない場合は failed で、agent install は停止します。システムが degraded の間(ユニットが失敗している)は warning |
docker | Docker が動作している(docker info) | Docker がない場合は ok(agent install がインストールするため)。ただし、エージェントがインストール済みの場合は failed。root なしで、ユーザーがグループ docker に属していない場合は skipped |
disk_space | /opt/ironflock と /var(Docker、apt、ログ)の空き容量 | /opt が 128 MiB 未満の場合は failed。エージェントのインストールと更新では、そこにバイナリが 2 つ置かれるためです。どちらかが 2 GiB 未満の場合は warning |
clock | ダウンロードサーバーの応答の Date(キャッシュが保持していた場合はその Age も考慮)に対する、このマシンの時刻 | 10 秒以内なら ok、5 分までは warning、それを超えると failed。署名付きリクエストと有効期間の短いトークンが拒否され、アプリのデータに誤った時刻が付くためです。時刻が大きくずれていると TLS 自体が失敗します。その場合は failed で、マシンの時刻が示されます。時刻同期(NTP) を参照してください |
dns | このマシンが自分で名前解決する名前:直接到達するホストと、プロキシ | 名前を解決できない。プロキシ経由で到達するホストの名前解決はプロキシが行います |
proxy | ネットワークのチェックが経由するプロキシと、その設定の出所:インストールの記録(/etc/ironflock/proxy.env)、それがなければ環境 | プロキシの URL でない場合は failed。記録がファイルにあり、root なしの場合は skipped(このファイルは root しか読めないため) |
download_tree | agent install が使うダウンロードサーバー上のエージェント:agent install が読み取るチャネルマップ(device-agent/manifest-v2.json、なければ manifest.json)と、このアーキテクチャ向けの production チャネルのエージェント。アプライアンスのミラーでは、agent install と同じく、ミラーが提供しないものを IronFlock クラウドで探します。ミラーがチャネルマップを提供しない場合はエージェント全体を、マップはあってもファイルがない場合はエージェントのファイルを探します | ダウンロードできるエージェントがない場合は failed で、agent install は停止します。アプライアンスのミラーでは、ミラーにもクラウドにもエージェントがない場合です。サーバーエラー(5xx)は warning で、ミラーにはなくクラウドにあるエージェントも warning です |
device_endpoint | .flock の device_endpoint_url が応答する | 応答がない。エージェントはそこで IronFlock に接続します |
docker_registry | .flock の docker_registry_url が応答する(https://<host>/v2/。ポート付きの場合は、LAN 上のアプライアンスのレジストリと同じく平文の HTTP) | 応答がない。デバイスはアプリのイメージをそこからプルします |
update_server | エージェントの更新サーバーにチャネルマップがある:.flock の update_url(アプライアンスのミラー)、それがなければ IronFlock クラウド | 応答がない、またはチャネルマップがない。エージェントはそこで更新を探します |
ダウンロードサーバーは、agent install が使うものです。--download-base、なければ環境変数 IRONFLOCK_DL_BASE、なければ .flock が指定するアプライアンスのダウンロードミラー(その update_url が IronFlock クラウドのホストでない場合)で、ミラーが提供しないものはクラウド、それもなければ IronFlock クラウドです(エージェントの取得元)。デバイスが到達する必要のあるホストは、ネットワーク要件 に一覧があります。
-c と root の有無による違い
最後の 3 つのチェックには .flock が必要です。-c で指定したもの、なければインストール済みのエージェントのものを使います。
| root で実行 | root なし | |
|---|---|---|
-c なし | インストール済みのエージェントの .flock のホスト | 最後の 3 つのチェックは skipped。インストール済みのエージェントの .flock は root しか読めないためです |
-c あり | 指定した .flock のホスト | 指定した .flock のホスト |
root なしでは、グループ docker に属していない場合の docker、インストールがプロキシを記録している場合の proxy も skipped になります。その場合、ホストから応答がないネットワークのチェック(dns では、名前を解決できない場合)も skipped になります。記録されたプロキシ経由なら応答が得られる可能性があるためです。privileges は確認できなかったすべてのチェックを示し、sudo ironflock doctor はそれらを実行します。
ネットワークのチェックの判定方法
- HTTP の応答が返ってくれば、ステータスにかかわらず、ホストは応答したとみなします。プロキシ経由の平文 HTTP リクエストに対する 502、503、504 は応答とみなしません。プロキシがホストに到達できないときに返すものだからです。
- TLS が拒否する証明書は、応答とみなしません。唯一の例外は、
.flockがappliance_domainを記載している場合の、アプライアンス自身の CA による証明書です。エージェントはこれを信頼します。 - チェックは、チェック
proxyのプロキシを経由します。ダウンロードと同じHTTPS_PROXY、HTTP_PROXY、NO_PROXYのルールに従い、リダイレクトの各リクエストにもこれを適用し、応答を 20 秒待ちます。 NO_PROXYのエントリーによってプロキシから外されたホストには、直接接続します。その方法で応答がない場合、所見にはそのエントリーが示され(例:(directly: instance-registry.ironflock.com is in NO_PROXY))、ヒントはそのエントリーを外すよう示します。設定がインストールの記録である場合は、それを行うagent configure --no-proxyもヒントに示されます。
出力
$ sudo ironflock doctor
Download base: https://instance-registry.ironflock.com/dl
Device file: /opt/ironflock/device-agent/device-config.flock
CHECK RESULT FINDING
privileges ok runs as root
system ok Debian GNU/Linux 12 (bookworm), amd64
systemd ok systemd runs this system
docker ok Docker 27.3.1 runs
disk_space ok 50.0 GB free for /opt and /var
clock ok within 10 s of the download server's clock
dns ok resolves instance-registry.ironflock.com, cbw.ironflock.com, europe-docker.pkg.dev
proxy ok none: the connections go direct
download_tree ok https://instance-registry.ironflock.com/dl has the agent 1.6.9 for amd64
device_endpoint ok cbw.ironflock.com answers
docker_registry failed europe-docker.pkg.dev cannot be reached: no answer within 20 s
update_server ok https://instance-registry.ironflock.com/dl has the agent's updates
What to do:
docker_registry: the device pulls its apps' images from there: let this machine reach europe-docker.pkg.dev on port 443, directly or through the proxy
Failed: docker_registry..flock のアプライアンスのミラーを使う場合は、1 行目にその旨が示されます:
Download base: http://10.0.0.5:15002/dl (the appliance's mirror of the .flock; the IronFlock cloud for what it does not give)--json の場合の例です。ここでは一部を省略して複数行で示していますが、コマンドは 1 行で出力します。
{
"result": "failed",
"checks": [
{"id": "privileges", "result": "ok", "finding": "runs as root"},
{"id": "docker_registry", "result": "failed", "finding": "europe-docker.pkg.dev cannot be reached: no answer within 20 s", "hint": "the device pulls its apps' images from there: let this machine reach europe-docker.pkg.dev on port 443, directly or through the proxy"}
],
"download_base": "https://instance-registry.ironflock.com/dl",
"flock": "/opt/ironflock/device-agent/device-config.flock"
}| フィールド | 値 |
|---|---|
result | チェックが失敗した場合は failed、警告があった場合は warning、それ以外は ok。スキップされたチェックによって失敗になることはありません |
checks | 上の順に並んだチェック:id、result、finding、および ok 以外のすべての結果では hint |
download_base | チェックしたダウンロードサーバー。アプライアンスのミラーの場合はミラーだけで、クラウドを調べたときは所見がクラウドを示します |
flock | ホストをチェックした .flock。ない場合は null |
どの出力にもシークレットは表示されません。チェックは .flock のうちホストだけを読み取り、プロキシのパスワードは xxxxx と表示されます。
終了コード
どのチェックも失敗しなかった場合、終了コードは 0 です。警告では失敗になりません。チェックが失敗した場合は 1 です。結果にどのチェックかが示され、エラーの行は続かず、--json では stdout にはエラーオブジェクトではなく結果が出力されます。-c の .flock を読み取れない場合は、エラーとともに 1 です。そのほかの終了コードについては、終了コード を参照してください。