Skip to Content

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 B

IronFlockOS デバイスのエージェントは、デバイスが登録されたときにイメージがセットアップしたもので、/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ディスクへの書き込みを開始し、完了を記録しなかったこと
doneIronFlockOS 上では、このシステムが 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_installtrue:エージェントはないが、以前のインストールがエージェントの段階に達する前に止まった。agent install はまずそれを元に戻します。それ以外の場合、このフィールドはありません
agent.layoutcurrent(/opt/ironflock/device-agent)、legacy(以前のインストーラーによる /opt/reagent)、migrating(エージェントが旧レイアウトを現在のレイアウトに移行している最中)
agent.dirエージェントのフォルダー
agent.versionエージェントのバイナリが -version で示すバージョン
agent.serviceunit と 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.installedIronFlock アプライアンスがインストールされている(そのユニット 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.urlUI のアドレス:その .env の HOME_URL。シークレットを含む .env のほかの部分は読み取りません
appliance.licenselicense.env にライセンスキーがある場合は present、ない場合は missing、その LICENSE_KEY がライセンスキー(UUID)でない場合は invalid。アプライアンスのどのコマンドもそのようなキーを無視し、テキストにもその旨が示されます。キーが表示されることはありません
appliance.serviceironflock.service。状態はエージェントのものと同じです。running は、ユニットがコンテナを起動したことを意味し、各コンテナが正常であることは意味しません
appliance.healthdocker 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.ironflockosIronFlockOS では 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_holdwait、copy、gave-up。リセットのホールドがある間のみ(上の表を参照)
os.data_missingtrue。/data をマウントできなかった場合のみ
os.install最後の os install が記録した内容。EFI 変数を持つすべての Linux で、記録があり読み取れる場合のみ:stage、time(RFC 3339、UTC)、reason(stopped と failed の場合)
os.apps_not_persistenttrue。/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 を実行してください
systemLinux で、Debian または Ubuntu ベース(インストールはパッケージを apt から取得します)か IronFlockOS であること、エージェントのダウンロード対象となるアーキテクチャほかのシステムでは failed、apt を持つほかの Linux では warning。failed の場合、agent install は停止します
systemdsystemd がシステムを動かしている(/run/systemd/system がある)systemd がシステムを動かしていない場合は failed で、agent install は停止します。システムが degraded の間(ユニットが失敗している)は warning
dockerDocker が動作している(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_treeagent 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 です。そのほかの終了コードについては、終了コード を参照してください。

Last updated on