デバイスエージェントのコマンド

ironflock agent コマンドは、Linux マシンをデバイスとして IronFlock に接続し、その後もデバイスエージェントを管理します。エージェントのインストール、別のデバイス設定やプロキシの設定、更新、停止、開始、ログの読み取り、そして削除に使います。

デバイスエージェント

デバイスエージェントは、マシンをデバイスとして IronFlock に接続し、デバイスのプロジェクトのアプリを Docker で実行するプログラムです。マシンがどのデバイスになるかは、IronFlock Studio がデバイスごとに発行するデバイス設定ファイル（.flock）で決まります（デバイスの接続）。

エージェントのコマンドは、すべて root が必要で、Linux で動作します。root でない場合は終了コード 3 で終了し、自分で sudo を呼び出すことはありません（root 権限）。macOS では、エージェントのコマンドは何かを調べる前に終了コード 3 で終了します。Linux マシン上で実行するか、Mac から --host で実行してください。IronFlockOS デバイスでは、イメージにシステムとともにエージェントが含まれています。そのため、そこでは agent install と agent remove は拒否され、agent configure -c は別の .flock でデバイスを登録します。

各コマンドは、グローバルフラグ --yes、--json、--download-base、--host、--hosts、--parallel も受け付けます（グローバルフラグ）。質問には端末が必要です。端末がない場合は --yes を指定してください（質問と確認）。

--host を付けると、コマンドは SSH 経由で別のマシン上で実行されます（SSH 経由のリモートマシン）。複数のマシンで同時に実行する場合（--host を複数回、または --hosts を指定）、agent restart、agent start、agent logs はそのまま実行されますが、agent logs --follow は --json と組み合わせられません。agent stop、agent update、agent configure、agent remove は、誰にも質問されないため --yes が必要です。また、.flock は 1 台のデバイスを示すため、agent configure は -c を受け付けません。agent install は、一度に 1 台のマシンでしか実行できません。

インストール済みのエージェントの構成

エージェントは、開始するたびに、ホストのいくつかの設定も自分で書き込みます。エージェントが動作し、そのためのメモリを確保するスライス ironflock.slice、systemd のウォッチドッグ、カーネルのクラッシュ設定、ジャーナルのサイズの上限です。

以前の IronFlock インストーラーがセットアップしたマシンでは、エージェントが旧レイアウト /opt/reagent（サービス reagent.service、ログ /var/log/reagent.log）のまま残っていることがあります。エージェントは、これを自分で /opt/ironflock/device-agent に移行します。マシンがどちらのレイアウトかは ironflock status で表示され、それが関係する場合は下の拒否の条件に記載しています。

ironflock agent install

デバイスエージェントを /opt/ironflock/device-agent に、Docker がない場合は Docker を、そしてデバイス向けのホストの既定設定をインストールし、マシンを .flock のデバイスとして IronFlock に接続します。エージェントはすぐに開始し、以降は自己更新します。

ironflock agent install -c <device.flock> [flags]

動作環境： systemd を備えた Debian または Ubuntu ベースの Linux。IronFlockOS では動作しません。root： 必要。質問： パッケージと Docker をインストールする前と、ホストの既定設定ごとに質問します。--yes はすべての質問に既定値で答えます。

マシンには、インターネット接続、--download-base で指定したダウンロードサーバーへの接続（ダウンロードベース）、または .flock が指定するアプライアンスのダウンロードミラーへの接続（エージェントの取得元）が必要です。デバイスが到達する必要のあるホストは、ネットワーク要件 に一覧があります。

エージェントの取得元

エージェントは、チャネルマップ、バイナリ、バイナリの .sha256 と .sig で構成されます。コマンドはこれらを次の順に取得します：

1. --download-base、なければ IRONFLOCK_DL_BASE：そのサーバーだけから取得します。
2. それもなければ、.flock が更新サーバー（update_url）として指定する IronFlock アプライアンスのダウンロードミラーから取得します。ただし、そのホストが IronFlock クラウドのホストでない場合に限ります。アプライアンスには到達できても ironflock.com には到達できないマシンは、この方法でインストールします。IronFlock クラウドの .flock では、クラウドから取得します。
3. それもなければ、IronFlock クラウド https://instance-registry.ironflock.com/dl から取得します。

コマンドは、使うダウンロードベースを stderr に示します：Download base: ... (from the device's .flock)、またはそれぞれ (from --download-base)、(from IRONFLOCK_DL_BASE)、(from default)。

アプライアンスのミラーを使う場合、ファイルはまずミラーから取得し、ミラーが提供しないものは、IronFlock クラウドのダウンロードベースの下の同じパスから取得します：

• チャネルマップ — その時点でミラーが提供しない場合（応答がない、マップがない、エラーステータス）は、すべてをクラウドから取得し、バージョンはクラウドのマップが示すものになります。ミラーが提供したマップが拒否された場合（署名、バージョンがない）は、ほかのサーバーと同じくインストールは失敗します。
• バイナリ、その .sha256 と .sig — ミラーが提供しないものは、それぞれクラウドから取得します。ミラーのファイルがチェック（チェックサム、署名）に合格しない場合は、3 つともクラウドから取得します。

フォールバックのたびに、ミラー、ファイル、理由を示す Warning: ... の行が stderr に出力され、--json では結果の warnings に項目が 1 つ追加されます。ミラーからもクラウドからもファイルを取得できない場合、インストールは失敗し、両方の取得元と両方の理由を示す 1 つのエラーを出します（neither the appliance's mirror ... nor the IronFlock cloud gives ...）。

ミラーは .flock の更新サーバーであり、プロキシを経由しません（プロキシ）。アプライアンス独自の CA による証明書を使う HTTPS のミラーは、マシンのシステムがその CA を信頼している場合にだけ使えます。ディストリビューションのパッケージと Docker は引き続きそれぞれのサーバーから、install.sh と ironflock は ironflock.com から取得します。--host では、ironflock はあなたのコンピューターからマシンに送られます。

インストール前のチェック

何かを変更する前に、コマンドは ironflock doctor のチェックのうち、インストールが成功するかどうかを判断するものを実行します。system、systemd、disk_space、clock、dns、proxy、download_tree、device_endpoint、docker_registry、update_server です。チェックは -c の .flock に対して、インストールのダウンロードベースとプロキシのフラグで実行されます。

このうち 4 つは、失敗するとインストールを停止します。そのままではインストールが確実に失敗するか、途中で失敗するためです：

メッセージには、チェック、その所見、そのヒントが示されます。それ以外の所見はすべて stderr の警告となり、インストールは続行します。エージェントは、ネットワークが許せばすぐに接続し、更新し、アプリをプルします。warning または skipped の結果でインストールが停止することはありません。インストールの前にすべてのチェックを確認するには、ironflock doctor -c device.flock を実行してください。

手順

1. インストールするパッケージを示して質問します。apt でインストールします。
2. マシンに Docker がない場合は、先に質問してから Docker をインストールします。
3. production チャネルのエージェントをダウンロードし、チェックサムと署名で検証します。検証済みのエージェントを取得できない場合、インストールはここで、以降のどの手順よりも前に停止します。
4. Docker を設定します。プロキシが指定されていればプロキシを、このインストールが持ち込んだ Docker またはまだ何も保持していない Docker では、エージェントのフォルダー内の data-root を設定します。イメージやコンテナを保持している Docker は、その設定とデータを保ちます。
5. ホストの既定設定（下の表）をセットアップします。それぞれ端末で選択でき、--yes は既定値を選びます。
6. エージェントを /opt/ironflock/device-agent にインストールし、開始します。

インストールはログインバナーも追加します。インストールが変更したものは、すべて /opt/ironflock/device-init/installed.json に書き込まれます。手順 4 以降の手順が失敗した場合、エラーは、その試行が記録されていること、同じコマンドを再度実行するとまずそれを元に戻すことを示します。コマンドがこのような以前の試行を見つけた場合は、チェックに合格した後でそれを元に戻します。元に戻すものを一覧表示して質問し、その後あらためてインストールします。

プロキシ

プロキシのフラグは、インストールのダウンロード、Docker、エージェントが使う企業プロキシを設定します。各設定はそのフラグから、なければ環境変数 HTTP_PROXY、HTTPS_PROXY、NO_PROXY（またはその小文字の形）から取得されます。

プロキシ URL は http://proxy.example.com:3128 のような形です。https:// と socks5:// も使え、スキームのない URL は http:// として扱われます。プロキシにログインが必要な場合は、http://[email protected]:3128 のように URL でパスワードを含めずにユーザーを指定し、パスワードは --proxy-password-file で渡します。コマンドは、ユーザーを記載したフラグの URL にパスワードを入れます。

警告：プロキシのパスワードを URL に書かないでください。コマンドラインは ps やシェルの履歴に表示されるため、パスワードを含む URL はコマンドラインの誤りとして拒否され、エラーメッセージにもその URL は繰り返されません。パスワードはファイルに 1 行で記載するか、--proxy-password-file /dev/stdin でパイプから渡してください（シークレット）。

--no-proxy のホストに加えて、次のホストもプロキシを経由しません（NO_PROXY）：localhost、127.0.0.1、::1、および IronFlock クラウドのホストでない場合のダウンロードサーバーと .flock の更新サーバー（その update_url）。アプライアンスや LAN 上のミラーがこれに当たります。IronFlock クラウドのホスト（ironflock.com、ironflock.dev とその配下のホスト、storage.googleapis.com）はインターネット上にあり、プロキシを経由します。

インストールは、Docker とエージェントのプロキシを、root だけが読める /etc/ironflock/proxy.env（モード 0600）に書き込み、Docker はそれを使うために再起動します。docker.service と ironflock-device-agent.service の systemd ドロップイン ironflock-proxy.conf はこのファイルの名前を記載するだけで、自身は設定を含みません。そのため systemctl show からすべてのユーザーにわかるのはファイルの名前だけで、その内容はわかりません。ホスト独自の Docker のドロップイン（docker.service.d/http-proxy.conf）はそのまま残ります。IronFlock の設定はその Environment= の行より優先され、警告がそのドロップインを示します。proxies を含む daemon.json は、その設定を保ちます。Docker はそれをほかのどの設定よりも優先するためです。

後で設定を変更するには、agent configure を使います。拠点全体のプロキシについては、企業プロキシの背後で を参照してください。

例

# エージェントをインストールする。コマンドは各手順の前に質問する
sudo ironflock agent install -c device.flock
# 質問なしでインストールし、デバイスがサスペンドしないようにする
sudo ironflock agent install -c device.flock --yes --disable-suspend
# ログインが不要なプロキシの背後でインストールする
sudo ironflock agent install -c device.flock --https-proxy http://proxy.example.com:3128
# ログインが必要なプロキシの背後でインストールする。パスワードはファイルから渡す
sudo ironflock agent install -c device.flock --https-proxy http://[email protected]:3128 --proxy-password-file proxy-password.txt

結果

$ sudo ironflock agent install -c device.flock --yes
Done: the IronFlock device agent runs (systemctl status ironflock-device-agent).
The device appears online in IronFlock within a minute.

{"action":"installed","device":"demo-device","agent_version":"1.6.9"}

warnings は、ファイルをアプライアンスのミラーではなく IronFlock クラウドから取得した場合にだけ結果に含まれます。Warning: の行と同じ内容で、ファイルごとに 1 項目です。

拒否する場合

コマンドラインの誤りは、何かが実行される前に終了コード 2 で終了します。パスワードを含むプロキシ URL、--proxy-password-file を指定せずにユーザーを記載したプロキシ URL、ユーザーを記載したプロキシ URL がないのに指定した --proxy-password-file、プロキシ URL ではない値です。プロキシ URL ではない環境のプロキシ変数も同様です。エラーには変数の名前が示され、その値は示されません。

次の場合、コマンドは終了コード 3 で拒否し、何も変更しません：

• root で実行されていない、またはマシンが Linux でない。
• マシンが IronFlockOS を実行している。root かどうかにかかわらず、ほかの何よりも先に拒否します。イメージにはシステムとともにエージェントと ironflock が含まれており、OS の更新のたびにシステム全体が置き換わるためです。メッセージは、デバイスが次回の起動時に IRONFLOCKOS パーティション上の .flock で登録されること、agent configure -c で今すぐ登録できることを示します。IronFlockOS のインストーラースティック上では、スティックはデバイスではないと示します。
• エージェントがすでにインストールされている。旧レイアウト /opt/reagent の場合も含みます。メッセージは agent configure と agent remove を示します。
• エージェントがマシンを旧レイアウトから移行している最中である。
• 以前のインストールがエージェントのセットアップ前に止まり、その時点で Docker の data-root を移動していて、その後 Docker がイメージやコンテナを保持している。その試行を元に戻すと、それらが削除されてしまうためです。
• チェック system、systemd、disk_space、download_tree のいずれかが失敗した。--yes を付けても変わりません。

質問に「いいえ」と答えた場合、または端末がなく --yes もない状態で質問した場合、コマンドは終了コード 4 で終了します。手順が失敗した場合は、終了コード 1 で終了します。

ironflock agent configure

インストールがセットアップしたもの、つまりデバイスの .flock、Docker とエージェントの企業プロキシ、またはその両方を変更します。変更を反映する必要があるものを再起動します。

ironflock agent configure [-c <device.flock>] [flags]

動作環境： エージェントがインストールされた Linux。IronFlockOS では -c のみ。root： 必要。質問： 新しいプロキシ設定のために Docker を再起動する前に質問します。--yes で回答します。

-c、プロキシのフラグ、またはその両方を指定します。どちらもない場合は変更するものがなく、コマンドラインの誤り（終了コード 2）になります。

別の .flock

-c を付けると、エージェントは指定された .flock を受け取って再起動し、マシンはその .flock のデバイスになります。アプリとそのデータは残ります。インストールが SSH ユーザーをセットアップした場合、SSH ユーザーは .flock に従います：

• 同じプロジェクトオーナーで、別のデバイスキー — 古い鍵は受け付けられなくなり、新しい鍵が受け付けられます。
• 別のプロジェクトオーナー — 新しいオーナーに SSH ユーザーが作られ、最初のオーナーの SSH ユーザーは agent remove と同じように削除されます。sudo のルール、鍵、そしてインストールが作成したアカウントであれば、ホームフォルダーを含むアカウントです。
• デバイスキーのない .flock — SSH ユーザーは削除され、新しいユーザーは作られません。

デバイスの所有者が変わるとき、コマンドを実行するのが最初のオーナー自身で、それも削除されるまさにそのアカウントで SSH 経由で実行していることがあります。アカウントを削除すると、そのセッションも終了します。そのため、コマンドは次の順序で動作します。新しいオーナーのアカウント（ユーザー、鍵、sudo のルール）をセットアップし、新しい .flock でエージェントを再起動し、その後で初めて最初のオーナーの sudo のルール、セッション、アカウント（同じオーナーの場合は古い鍵だけ）を削除します。古いアクセス手段がなくなる前に、デバイスには新しいアクセス手段があり、オンラインになっています。セッションが終了する前に、stderr の 1 行がその旨を示します。たとえば Removing the account anna, ...: a session of anna ends here. です。

• 新しい .flock でエージェントが再起動しない場合、最初のオーナーはアクセスを保持します。誰かがデバイスに入れる必要があるためです。
• 新しいオーナーの SSH ユーザーだけが失敗した場合でも、最初のオーナーのアクセスは削除されます。デバイスの所有者は変わっており、オンラインだからです。
• まだ削除されていないアクセスが誰のものかは、/opt/ironflock/device-init/installed.json（users_to_remove）に記録されます。以降の agent configure -c と agent remove は、そのたびに削除を再試行します。
• 新しい .flock が再びセットアップするアカウントは、削除されません（オーナー A、次に B、再び A の場合）。
• 最初の変更を行った後は、端末や SSH セッションが失われてもコマンドは止まりません。

--host 経由の場合、マシン上の .flock のコピーは、コマンドが読み取った時点で削除されます。--host のログインユーザーが削除されるアカウントの場合、SSH セッションはそのアカウントとともに終了します。その場合、ここでの実行は接続が切れたときと同じく終了コード 255 で終了し、マシン上のコマンドは最後まで実行を続けます。実行用フォルダー ironflock.XXXXXXXXXX は、そのバイナリとともにマシン上に残ります。一時フォルダーにある場合はそれが片付けられるまで残り、アカウントのホームにある場合はアカウントとともに削除されます。

IronFlockOS の場合

-c を付けると、コマンドは、IronFlockOS が新しいルートスロットの初回起動のたびに行うのと同じ方法でデバイスを登録します。登録済みのデバイスでも、まだ登録していないデバイスでも同じです。指定した .flock はエージェントのコピー、つまり /data 上の /opt/ironflock/device-agent/device-config.flock になり、デバイスはそこから次の順序でセットアップされます。プロジェクトオーナーの SSH ユーザー、WiFi、デバイス名からのホスト名（/etc/ironflockos/enroll.conf に hostname-from-flock=no とある場合を除く）、新しい .flock で再起動するエージェント、そして前の所有者のアクセスの削除です。

次回の OS 更新は、同じコピーから新しいルートスロットを登録します。指定したファイルは元の場所に残ります。手順が失敗してもエージェントは新しい .flock で再起動しますが、最初のオーナーのアクセスが削除されるのは、エージェントが再起動した後だけです。その場合、コマンドは終了コード 1 で終了し、失敗した各手順を示します。同じコマンドを再度実行すると、それらの手順を繰り返します。

IronFlockOS では、プロキシのフラグは拒否されます。IronFlockOS は、Docker、エージェント、時刻同期が使うプロキシを /data 上の /etc/ironflockos/proxy.conf に保持し、IRONFLOCKOS パーティション上の proxy.conf が次回の起動時にそれを置き換えます。

プロキシ設定

• 指定した各プロキシのフラグはその設定を置き換え、ほかの設定は残ります。--https-proxy だけを指定すると、HTTPS プロキシが変わり、HTTP プロキシとプロキシを経由しないホストはそのままです。
• --proxy-password-file のパスワードは、指定した URL のうちユーザーを記載したものに入ります。URL を指定しない場合は、デバイスの設定の URL のうちユーザーを記載したものに入ります。そのため、新しいパスワードはファイルだけで設定できます。
• --no-proxy、およびプロキシがなかったデバイスの最初のプロキシには、localhost、127.0.0.1、::1 と、IronFlock クラウドのホストでない場合のエージェントの .flock の更新サーバー（アプライアンスのもの）も含まれます。
• --remove-proxy は設定を削除します。ほかのプロキシのフラグとは組み合わせられません。
• お使いの環境のプロキシ変数は、ここでは何も変えません。有効なのはフラグだけです。

プロキシを経由しないホストの一覧は、--no-proxy で別の一覧を指定しない限り、コマンドが見つけたとおりに残ります。この一覧に IronFlock クラウドのホストが含まれている場合は、警告がそのホストを示し、それを除いた一覧を指定する agent configure --no-proxy も示します。プロキシ経由でしかインターネットに到達できないデバイスは、クラウドのダウンロードサーバー instance-registry.ironflock.com がこの一覧にある間、エージェントを更新できません。

設定は root だけが読める /etc/ironflock/proxy.env に保持され、docker.service と ironflock-device-agent.service のドロップイン ironflock-proxy.conf がこのファイルを記載します。設定が変わる場合、コマンドは変更前と変更後の設定を、パスワードを除いて表示します。その後、Docker とエージェントが再起動します。Docker を再起動するとデバイスのアプリが一時的に停止するため、コマンドはその旨を示して質問します。--yes で回答します。パスワードを stdin で渡す場合は質問する端末がないため、--yes を指定してください。

• Docker の daemon.json が proxies を設定している場合（Docker はこれらの設定よりそちらを優先します）、および何も変わらない場合は、Docker は再起動せず、何も質問されません。
• ドロップインがないだけのユニットにはドロップインが追加され、そのユニットだけが再起動します。
• ホスト独自の Docker のドロップインはそのまま残ります。プロキシ変数を設定する、エージェントまたは Docker の別のドロップインは、警告で示されます。IronFlock の設定は、自身が設定する変数ごとにそれを上書きします。すべてのユーザーが読めるプロキシのパスワードを含むドロップインや daemon.json も、警告で示されます。
• Docker の再起動が失敗してもエージェントは再起動し、その逆も同様です。エラー（終了コード 1）は、まだ古い設定で動作しているユニットと、設定を適用する systemctl restart を示します。2 回目の実行では設定が反映済みであることがわかり、何も再起動しません。
• 設定を書き込めない場合は何も再起動せず、エラーはコマンドを再度実行するよう示します。

以前のインストールが http-proxy.conf ドロップインの Environment= の行に書き込んだプロキシ設定は、すべてのユーザーが systemctl show でパスワードも含めて読めます。この設定は、agent configure を実行すると、-c だけの実行であっても、/etc/ironflock/proxy.env に移されます。古いファイルのコピーは残りません。通常、移行では値が保たれるため、何も再起動せず、何も質問しません。ユニットが使うプロキシが変わる場合は、コマンドはその理由を示し、そのユニットの変更前と変更後のプロキシを表示して質問します。設定ファイルに保持できない値（ホストやプロキシを経由しないホストの一覧に含まれるシングルクォート、制御文字）は移されません。プロキシのフラグを付けない実行ではその値を残して警告し、値をあらためて指定するフラグを示します。

例

# このマシンを別の .flock のデバイスにする
sudo ironflock agent configure -c new-device.flock
# ログインが必要な HTTPS プロキシを設定する。パスワードはファイルから渡す
sudo ironflock agent configure --https-proxy http://[email protected]:3128 --proxy-password-file proxy-password.txt
# 新しいプロキシのパスワードだけを、質問なしで stdin から読み取って設定する
sudo ironflock agent configure --proxy-password-file /dev/stdin --yes < proxy-password.txt
# プロキシ設定を削除する。Docker とエージェントは直接接続する
sudo ironflock agent configure --remove-proxy

結果

$ sudo ironflock agent configure -c new-device.flock
Device configuration updated; the agent restarted.
$ sudo ironflock agent configure --https-proxy http://[email protected]:3128 --proxy-password-file proxy-password.txt
The proxy settings of Docker and the agent change:
  HTTP proxy:   none (unchanged)
  HTTPS proxy:  none -> http://[email protected]:3128 (with a password)
  No proxy for: localhost,127.0.0.1,::1
Docker restarts for the new settings: the apps of the device stop for a moment and start again.
? Continue? Yes
Proxy settings updated: HTTPS through http://[email protected]:3128 (with a password); not for localhost,127.0.0.1,::1.
Restarted: docker.service, ironflock-device-agent.service.

IronFlockOS では、-c は登録を報告します：

Device configuration updated: this device enrolled as new-device, as IronFlockOS enrolls it at every new root slot; the agent restarted.

{"action":"configured","device":"new-device","restarted":["ironflock-device-agent.service"]}

{"action":"configured","proxy":{"password":false,"changed":true,"moved":false},"restarted":["docker.service","ironflock-device-agent.service"]}

拒否する場合

コマンドラインの誤りは、終了コード 2 で終了します。変更するものがない、--remove-proxy とほかのプロキシのフラグの組み合わせ、パスワードを含むプロキシ URL、--proxy-password-file を指定せずにユーザーを記載したプロキシ URL、どれもユーザーを記載していない URL と --proxy-password-file の組み合わせ、プロキシ URL でもホストの一覧でもない値です。

次の場合、コマンドは終了コード 3 で拒否し、何も変更しません：

• エージェントがインストールされていない（メッセージは agent install を示します）。ただし IronFlockOS では、-c はまだ登録していないデバイスを登録します。
• エージェントがマシンを旧レイアウトから移行している最中である。
• プロキシのフラグが指定され、エージェントがまだ旧レイアウト /opt/reagent で動作している。エージェントが移行を終えれば（レイアウトは ironflock status で表示されます）、同じコマンドが動作します。
• IronFlockOS でプロキシのフラグが指定された。-c の有無は問いません。
• プロキシのないデバイスで --no-proxy または --proxy-password-file だけが指定された、またはデバイスのどのプロキシ URL もユーザーを記載していないのに、パスワードファイルだけが指定された。
• プロキシのフラグを指定しても、/etc/ironflock/proxy.env に保持できない旧形式の値が残る。メッセージは、その値をあらためて指定するフラグを示します。

IronFlockOS では、登録で .flock が保たれない場合、-c は終了コード 3 で拒否されます：

• ファクトリーリセットが要求されていてまだ開始していない（os reset が書き込む /boot/efi/factory-reset.conf）、または開始している（/boot/efi/factory-reset.keep）。次回の起動で、コマンドがセットアップしたものが消去されるためです。
• ファクトリーリセットが未完了であるか断念されていて、リセットとともに置かれたファイルを保留している（/run/ironflockos/factory-reset-hold。詳しくは ironflock status で表示されます）。
• /data をマウントできなかったため、エージェントのコピーがルートスロットに置かれてしまう。その場合は IRONFLOCKOS パーティション上の .flock を使います。
• IRONFLOCKOS パーティション上に .flock がある。デバイスは次回の起動時にそれで登録され、メッセージはそのファイルを示します。
• コマンドが IronFlockOS のインストーラースティック上で実行されている。スティックはデバイスではありません。
• システムに /usr/lib/ironflock/image.json がない、または旧レイアウトのエージェントがある。

ironflock agent update

エージェントをそのチャネルのリリースに自己更新させ、その動作を追跡します。エージェントは開始するたびに新しいリリースを探すため、コマンドはエージェントを再起動して結果を報告します。デバイスは一時的に IronFlock 上でオフラインになりますが、アプリは動作し続けます。

ironflock agent update [flags]

動作環境： エージェントがインストールされた Linux。root： 必要。質問： 再起動で何が起きるかを示した後に質問します。--yes で回答します。

このコマンドに固有のフラグはなく、バージョンも指定しません。エージェントはそのチャネル（production、または IronFlock のテストプラットフォームでは test）に従い、更新サーバーから更新します。更新サーバーは .flock の update_url（アプライアンスのミラー）、なければ IronFlock クラウドです。--download-base はこれを変えません。

エージェントは次の順序で動作します：

1. チャネルのリリースを読み取ります。このデバイスで 2 回失敗したリリースは、より新しいリリースが出るまで再びダウンロードされません。
2. より新しいリリースを自分のフォルダーにダウンロードし、その署名を検証します。
3. 新しいバージョンを配置し、ダウンロードの 10 秒後に再起動してそのバージョンに切り替えます。最後に IronFlock に接続したのが 12 分〜1 日前の場合は、更新を保留します。更新は、接続できることがわかっているバージョンから有効化するためです。
4. 新しいバージョンは試用期間に入ります。開始から 10 分以内に IronFlock に接続し、2 分間動作し続ける必要があります。そうならない場合、またはその前に 3 回停止した場合、エージェントは前のバージョンに戻ります。
5. ロールバックの後は、前のバージョンが接続する必要があります。接続できれば、原因は新しいバージョンにあります。新しいバージョンは次回の更新でもう一度試され、2 回目に失敗すると、より新しいリリースが出るまでブロックされます。前のバージョンも 10 分以内に接続できない場合、エージェントはネットワークが原因と判断し、新しいバージョンは次回の更新で再び試されます。

コマンドは、エージェントのフォルダーにある update-state.json とエージェントのログで、この経過を追跡します。どちらも再起動前の内容は読み取りません。進捗は、--json でもテキストの行として stderr に出力されます。ダウンロード中は、1 分ごとにそれまでのダウンロード量を表示します。

終了コード 1 の場合も結果は出力され、stderr には Error: の行が出力されます。--json ではエラーオブジェクトは続かず、stdout には結果が出力されます。

例

# エージェントを更新する。コマンドは再起動の前に質問する
sudo ironflock agent update
# 質問なしで更新し、結果を JSON で読み取る
sudo ironflock agent update --yes --json

結果

$ sudo ironflock agent update --yes
The agent 1.6.9 restarts now and looks for a newer release on its channel: the device is offline in IronFlock for a moment, its apps keep running.
A newer release is downloaded and started. It has to connect to IronFlock within 10 minutes and stay up for 2, or the agent goes back to 1.6.9.
The agent restarted; it looks for a newer release.
Its channel offers 1.7.0: the agent downloads it.
Activating 1.7.0: the agent restarts into it.
1.7.0 runs on probation: it has to connect to IronFlock within 10 minutes and stay up for 2.
The agent was updated from 1.6.9 to 1.7.0: 1.7.0 connected to IronFlock and passed its probation.

最新のエージェントと、新しいバージョンがロールバックされたエージェントの例です：

{"outcome":"current","version":"1.7.0","channel_version":"1.7.0"}

{"outcome":"rolled_back","version":"1.6.9","channel_version":"1.7.0","failed_version":"1.7.0","reason":"did not connect within 10m0s","retry":"next_update"}

拒否する場合

エージェントがインストールされていない場合（メッセージは agent install を示します）、エージェントがマシンを旧レイアウトから移行している間、エージェントが旧レイアウトで動作している場合（その更新は、コマンドが追跡できる状態を残しません）、エージェントが 1.3.0 より古い場合（1.3.0 は、ユニットの下で自己更新する最初のバージョンです）、コマンドは終了コード 3 で拒否します。

再起動が失敗した場合、および更新がエージェントの所定の時間内に進まない場合、コマンドは終了コード 1 で失敗し、エラーは確認すべき場所を示します。所定の時間は、再起動後のエージェントのチェックが 3 分以内、ダウンロードが 30 分以内、有効化が 3 分以内、試用期間中の新しいバージョンの各開始が 12 分以内、ロールバック後のエージェントの判定が 12 分以内、そして全体で 84 分以内です。エージェントは単独で処理を続け、ironflock status でその状況を確認できます。

Ctrl-C は追跡をやめるだけで、更新は止めません。コマンドは終了コード 130 で終了します。

ironflock agent remove

デバイスエージェントを削除し、インストールが記録した内容を元に戻します。Docker 自体とパッケージは、インストールされたまま残ります。

ironflock agent remove [flags]

動作環境： エージェントがインストールされた Linux。IronFlockOS では動作しません。root： 必要。質問： 削除するものを一覧表示した後に質問します。質問では「No」があらかじめ選択されているため、Enter だけでは何も削除されません。

このコマンドに固有のフラグはありません。削除するものは次のとおりです：

• エージェント — エージェント、そのデータベース、/opt/ironflock/device-agent。Docker がデバイスのアプリとそのデータをエージェントのフォルダーに保存している場合は、それらも一緒に削除されます。
• SSH ユーザー — アカウントは、インストールが作成した場合にだけ削除されます。以前からあったアカウントでは、その authorized_keys からデバイスキーだけが削除され、ファイルはユーザーのものとして残ります。agent configure -c による削除が失敗した、以前のプロジェクトオーナーのアクセスも削除され、「(a removal that had failed)」と付けて一覧表示されます。
• ホストの既定設定 — WiFi のプロファイル、ログインバナー、マスクしたスリープターゲット。
• インストールが書き込んだ、または置き換えたファイル — 元のファイルが、そのモード、所有者、グループとともに戻ります。
• プロキシ設定 — /etc/ironflock/proxy.env とそれを記載するドロップイン、そして以前のインストールが http-proxy.conf ドロップインに残したプロキシ設定。代わりに戻るものはありません。削除後、Docker には IronFlock によるプロキシがなく、コマンドはプロキシのパスワードをどこにも書き込んでいません。Docker に IronFlock によるプロキシがあった場合は、質問の前の一覧にその旨が示されます。
• エージェントがホストに自分で書き込んだ設定 — スライス ironflock.slice とそのユニットのドロップイン 10-ironflock-resources.conf、systemd のウォッチドッグ（/etc/systemd/system.conf.d/10-ironflock-watchdog.conf）、カーネルのクラッシュ設定（/etc/sysctl.d/60-ironflock-crash-recovery.conf。カーネルは次回の起動までこの設定を保持します）、ジャーナルの上限（/etc/systemd/journald.conf.d/10-ironflock.conf）。
• エージェントのレジストリへのログイン — エージェントが停止した後、コマンドは .flock が記載するレジストリ（docker_registry_url）について、またアプライアンスのデバイスでは registry.<appliance_domain> について、docker logout を実行します。/root/.docker/config.json のほかのログインには触れません。Docker がない、または失敗しても削除は止まらず、どのログインが削除されなかったかを 1 行で示します。

ホスト独自の Docker のドロップインはそのまま残ります。削除のために再起動しない Docker（データがエージェントのフォルダーになかったもの）は、次に再起動するまで、起動時のプロキシを使い続けます。

コマンドは削除するものを stderr に一覧表示してから質問します。--json では、一覧は結果のフィールド removed になります。削除を始めた後は、端末や SSH セッションが失われてもコマンドは止まりません。削除される SSH ユーザーのセッションは一緒に終了し、それがコマンドを実行しているセッションであることもありますが、削除は最後まで続きます。

例

# エージェントを削除する。コマンドは削除されるものを一覧表示して質問する
sudo ironflock agent remove
# 質問なしでエージェントを削除する
sudo ironflock agent remove --yes

結果

$ sudo ironflock agent remove --yes
This removes:
  - the agent, its database and /opt/ironflock/device-agent (with Docker's images and containers)
  - the user operator and its home directory
  - /etc/profile.d/ironflock-motd.sh
The IronFlock device agent was removed from this machine.

{"action":"removed","removed":["the agent, its database and /opt/ironflock/device-agent (with Docker's images and containers)","the user operator and its home directory","/etc/profile.d/ironflock-motd.sh"]}

拒否する場合

エージェントがインストールされていない場合、およびエージェントがマシンを旧レイアウトから移行している間、コマンドは終了コード 3 で拒否します。IronFlockOS では、root かどうかにかかわらず、ほかの何よりも先に拒否します。イメージにはシステムとともにエージェントが含まれており、OS の更新や次回の登録のたびに再びセットアップされるためです。メッセージは ironflock os reset を示します。これは、デバイスを、IronFlock での ID を持たない、書き込んだばかりの IronFlockOS の状態に戻すコマンドです。IronFlockOS のインストーラースティック上では、スティックはデバイスではないと示します。

「いいえ」の回答、または端末がなく --yes もない状態での質問は、終了コード 4 でコマンドを終了させます。

ironflock agent restart

エージェントのサービスを再起動し、エージェントが再び動作していることを確認します。そのユニットが 1 つのプロセスで 5 秒間動作し続ける必要があります。その数秒間、デバイスは IronFlock 上でオフラインになりますが、アプリは動作し続けます。

ironflock agent restart [flags]

動作環境： エージェントがインストールされた Linux。root： 必要。質問： なし。

このコマンドに固有のフラグはありません。サービスは ironflock-device-agent.service です。エージェントを経由する端末（IronFlock Studio のデバイスの端末、または IronFlock 経由の SSH）で実行すると、再起動によってそのセッションは終了します。デバイスは 1 分以内に戻ります。

# エージェントを再起動する
sudo ironflock agent restart
# 再起動し、新しいプロセスを JSON で読み取る
sudo ironflock agent restart --json

$ sudo ironflock agent restart
The agent restarted: ironflock-device-agent.service runs, with process 4242.

{"action":"restarted","unit":"ironflock-device-agent.service","state":"running","main_pid":4242}

state は再起動後のユニットの状態で、ironflock status と同じ名前で示されます。main_pid はエージェントのプロセスで、再起動のたびに新しくなります。

拒否する場合： エージェントがインストールされていない（メッセージは agent install -c <file> を示します）、エージェントがマシンを旧レイアウトから移行している、systemd がエージェントのユニットを知らない（メッセージは agent remove を示します）。いずれも終了コード 3 です。

失敗する場合： エージェントが起動しない、つまり systemd がユニットを開始できない、またはそのプロセスが 5 秒以内に終了した場合は、終了コード 1 です。エラーは、ユニットと、その最後のログ行がある場所を示します。エージェントのログ（agent logs）とジャーナル（journalctl -u <unit>）です。

ironflock agent stop

エージェントのサービスを停止します。デバイスは IronFlock 上でオフラインになり、IronFlock 経由のリモートアクセスもエージェントとともに失われます。その経路で接続したセッション（IronFlock Studio のデバイスの端末、IronFlock 経由の SSH）は終了し、エージェントが再び動作するまで、IronFlock はデバイスに到達できません。アプリを実行しているのはエージェントではなく Docker であるため、アプリは動作し続けます。

ironflock agent stop [flags]

動作環境： エージェントがインストールされた Linux。root： 必要。質問： エージェントを停止すると何が止まるかを示した後に質問します。--yes で回答します。

このコマンドに固有のフラグはありません。agent start でエージェントは再び開始し、次回の起動時にも開始します。停止したエージェントを、IronFlock 経由で再び開始することはできません。動作していないエージェントには停止するものがないため、その場合、コマンドは何も質問せず、結果には action がありません。

# エージェントを停止する。コマンドは何が止まるかを示して質問する
sudo ironflock agent stop
# 質問なしで停止する
sudo ironflock agent stop --yes

$ sudo ironflock agent stop --yes
Stopping the agent (ironflock-device-agent.service) takes this device offline in IronFlock.
The remote access through IronFlock goes with it: a session that came that way (the device's terminal in Studio, SSH through IronFlock) ends.
The apps keep running. 'sudo ironflock agent start' starts the agent again, and so does the next boot.
The agent is stopped (ironflock-device-agent.service): the device is offline in IronFlock, and its apps keep running. 'sudo ironflock agent start' starts the agent again.

{"action":"stopped","unit":"ironflock-device-agent.service","state":"stopped"}

拒否する場合： agent restart と同じく、終了コード 3 です。「いいえ」の回答、または端末がなく --yes もない状態での質問は、終了コード 4 でコマンドを終了させます。

ironflock agent start

エージェントのサービスが動作していない場合に開始し、agent restart と同じように、エージェントが起動したことを確認します。そのユニットが 1 つのプロセスで 5 秒間動作し続ける必要があります。すでに動作しているエージェントはそのままにし、その場合、結果には action がありません。

ironflock agent start [flags]

動作環境： エージェントがインストールされた Linux。root： 必要。質問： なし。このコマンドに固有のフラグはありません。

# エージェントを開始する
sudo ironflock agent start
# 開始し、そのプロセスを JSON で読み取る
sudo ironflock agent start --json

$ sudo ironflock agent start
The agent started: ironflock-device-agent.service runs, with process 4242. The device appears online in IronFlock within a minute.

--json を付けた場合、すでに動作しているエージェントでは次のようになります：

{"unit":"ironflock-device-agent.service","state":"running","main_pid":4242}

拒否する場合と失敗する場合： agent restart と同じです。エージェントがインストールされていない、エージェントがマシンを旧レイアウトから移行している、systemd がエージェントのユニットを知らない場合は終了コード 3、エージェントが起動しない場合は終了コード 1 です。

ironflock agent logs

エージェントのログ /var/log/ironflock/device-agent.log と、エージェントがローテーションしたファイルを表示します。何も変更しません。

ironflock agent logs [flags]

動作環境： エージェントがインストールされた Linux。ファイルを読み取るため、systemd は不要です。root： 必要。エージェントはログを root 専用（モード 0600）で書き込むためです。質問： なし。

エージェントは、ログが 100 MB に達すると、同じフォルダー内でその名前を device-agent-<time>.log に変え、新しいログを始めます。保持するのは 2 つです。コマンドは、ログとこれらのファイルを読み取ります。

エージェントは 1 行に 1 つの JSON オブジェクトを書き込みます。エントリーの時刻（秒単位）、レベル、メッセージ、その他のフィールドです。テキスト形式では、IronFlock Studio がエージェントのログを表示するのと同じように、UTC の時刻、レベル、メッセージ、そのエラーでエントリーを表示します。クラッシュ時のスタックトレースのように、エントリーではない行はそのまま表示されます。制御文字はエスケープされる（\n、\x1b）ため、1 つのエントリーは端末上で 1 行になり、端末を操作することはできません。--json では、各行が stdout 上の 1 つの JSON オブジェクトになります。エージェントが書き込んだとおりのすべてのフィールドを含むエントリー、またはエントリーではない行の場合は {"message":...} です。

• --since は、その時刻またはそれ以降の最初のエントリーから始まります。行は、エージェントが書き込んだ順のままです。時刻のない行は、その前のエントリーに属します。
• --follow では、行は完全に書き込まれた時点で表示されます。エージェントが新しいファイルを始めると、まず古いファイルの残りが、次に新しいファイルが先頭から表示されます。まだ存在しないログは、作成されるまで待ちます。Ctrl-C は終了コード 0 でコマンドを終了させます。--host 経由では、Ctrl-C は終了コード 130 で実行を終了させます。
• エージェントがまだログを書き込んでいない場合は、stderr にその旨が示され、stdout は空のままで、終了コードは 0 です。

例

# 最後の 100 行
sudo ironflock agent logs
# 直近 1 時間のすべて
sudo ironflock agent logs --since 1h
# 最後の 20 行と、その後 Ctrl-C までのすべての新しい行
sudo ironflock agent logs --follow --lines 20
# 直近 10 分間を JSON で。1 行に 1 つのオブジェクト
sudo ironflock agent logs --since 10m --json

結果

$ sudo ironflock agent logs --lines 3
2026-11-10T11:58:02Z INFO connected to IronFlock
2026-11-10T11:58:03Z INFO 3 apps running
2026-11-10T11:59:40Z ERROR pulling demo-app:1.2 failed: context deadline exceeded

{"level":"info","time":"2026-11-10T11:58:02Z","caller":"agent.go:212","message":"connected to IronFlock"}

拒否する場合

期間でも時刻でもない --since、負の期間、数値でも all でもない --lines は、コマンドラインの誤り（終了コード 2）です。root で実行されていない場合、およびエージェントがインストールされていない場合（メッセージは agent install -c <file> を示します）、コマンドは終了コード 3 で拒否します。