ログインとデバイスの管理
これらのコマンドは、実行するマシンではなく、IronFlock インスタンス(クラウドまたはアプライアンス)と通信します。ironflock login はこのマシンに API キー を保存し、whoami はキーが属するアカウントを示し、logout はキーを削除します。その後、ironflock device create、list、delete で、プロジェクトのデバイスを操作します。agent install、os flash、os install は、--project と --name を使ってデバイスを作成することもできます。
どのコマンドも root は不要で、すべて Linux、macOS、Windows で動作します。これらはこのマシン上でだけ動作します。--host と --hosts は終了コード 2 で拒否され、キーも認証情報ファイルも、別のマシンに送られることはありません(SSH 経由のリモートマシン)。
login と whoami には、API サービスが GET /v1/ironflock/whoami に応答するインスタンスが必要です(API エンドポイント)。IronFlock クラウドは応答します。このルートを持たないインスタンスは 404 を返し、コマンドはその旨を表示します。IronFlock アプライアンスは、IronFlock API サービスを実行するようになると、このルートを提供します。まだこのサービスを実行していないアプライアンスのリリースでは、これらのコマンドは使えません。コマンドはインスタンスの API とだけ通信し、ironflock のほかのすべてのリクエストと同じく、環境のプロキシ(HTTPS_PROXY、NO_PROXY)を使います。
インスタンス
既定値はクラウドです。--instance、それがなければ環境変数 IRONFLOCK_INSTANCE で、別のインスタンス(アプライアンス)を指定します。手元にあるものを指定すれば、コマンドがそこから API のアドレスを導き出します:
| 指定するもの | API |
|---|---|
何も指定しない、または ironflock.com、studio.ironflock.com、api.ironflock.com | https://api.ironflock.com |
アプライアンスのドメイン factory.example.com | https://api.factory.example.com |
Studio を開くアドレス https://factory.example.com/projects/12 | https://api.factory.example.com |
API 自身のホスト api.factory.example.com | https://api.factory.example.com |
スキームがない場合は https:// とみなします。プレーンな http は、ループバックアドレス(このマシン上のスタック)に対してだけ受け付けます。ループバック以外の IP アドレスは拒否されます。アプライアンスの API には名前でアクセスします。プレーン HTTP モードのアプライアンスには api.<domain> がなく、login は到達できません。インスタンスの証明書は、このマシンのトラストストアと、--ca-cert の認証局(PEM ファイル。複数ある場合は複数回指定)に照らしてチェックされます。たとえば、アプライアンスの証明書に署名した自社の CA です。このチェックを無効にする方法はありません。
認証情報ファイル
login は、ユーザーの設定フォルダー内の ironflock フォルダーにある credentials.json にキーを保存します。Linux では ~/.config/ironflock/、Mac では ~/Library/Application Support/ironflock/、Windows では %LOCALAPPDATA%\ironflock\credentials\ です。このファイルはインスタンスごとに 1 つのエントリを持ち、あなただけが読めます。他人が読み取りや変更をできるファイルやフォルダーは使われません。その場合、コマンドは終了コード 3 で終了し、修復方法を示し、何も変更しません。
スクリプトや CI 向けには、IRONFLOCK_API_KEY に、すべてのコマンドが保存済みのキーの代わりに使うキーを設定できます。login がこの変数を読んだり保存したりすることはありません。
| 変数 | 意味 |
|---|---|
IRONFLOCK_INSTANCE | --instance を指定しない場合のインスタンス |
IRONFLOCK_API_KEY | 保存済みのキーの代わりに使う API キー |
HTTPS_PROXY、NO_PROXY | インスタンスへのリクエストに使うプロキシ |
ironflock login
キーが誰のものかをインスタンスに問い合わせたうえで、そのインスタンス用の API キーを保存します。
ironflock login [--key-file <file>] [--instance <domain or URL>] [--ca-cert <file>]...$ ironflock login --key-file key.txt --instance factory.example.com
Logged in to https://api.factory.example.com as operator (account 12). The key is stored in /home/operator/.config/ironflock/credentials.json.動作環境: Linux、macOS、Windows。root: 不要。質問: なし。
| フラグ | 意味 |
|---|---|
--key-file <file> | キーを含むファイルまたはパイプ。既定値:端末でない場合の標準入力 |
--instance <instance> | インスタンス。既定値:IRONFLOCK_INSTANCE、なければクラウド |
--ca-cert <file> | このマシンの認証局に加えて信頼する認証局。複数ある場合は複数回指定 |
- キーがコマンドラインに載ることはありません。 キーはファイルまたはパイプから受け取り、コマンドが端末でキーを尋ねることはありません。どちらもない場合は終了コード 2 で終了し、キーの渡し方を示します。キーの前後の空白は取り除かれます。キーは
0-9とa-fからなる 40 文字です。それ以外はリクエストの前に拒否され、エラーにキーが繰り返されることはありません。 - 何かを保存する前に、キーが誰のものかをインスタンスに問い合わせます。インスタンスが受け付けないキー、応答できないインスタンス、信頼されていない証明書、到達できないインスタンスの場合は終了コード 1 で終了し、それまでに保存されていたものはそのまま残ります。
- すでにログインがあるインスタンスへのログインは、それを置き換えます。 ほかのインスタンスのログインは残ります。
- リクエストはリダイレクトに従いません。 キーがほかのホストに送られないようにするためです。
--jsonでは、結果はaction(logged_in)、instance、account_id、username、scopes、restriction、credential_fileを持つ 1 つのオブジェクトです。
キーを自分だけが読めるファイルに保存してから、ログインします:
(umask 077; cat > key.txt)
ironflock login --key-file key.txtcat > key.txt の後に、ターミナルにキーを入力または貼り付けて Ctrl-D で終え、login がキーを保存したら key.txt を削除してください。
ironflock whoami
キーが属するアカウントを示し、キーで何ができるかを表示します。
ironflock whoami [--instance <domain or URL>] [--ca-cert <file>]...$ ironflock whoami --instance factory.example.com
Instance: https://api.factory.example.com
Account: operator (12)
Scopes: devices:read, devices:write
Restriction: the projects 3
Key: stored by 'ironflock login' on 2026-11-19 10:00 UTCキーは、IRONFLOCK_API_KEY が設定されていればそれ、なければ login がそのインスタンス用に保存したものです。どちらもない場合、コマンドは終了コード 3 で終了し、実行すべき login を示します。Scopes はキーの スコープ で、スコープがない場合は none です。Restriction は none: everything the account may do、the projects 3, 5、the app 5 のいずれかです。--json では、結果に instance、account_id、username、scopes、restriction、key_source(environment または credential_file)と、保存済みのキーの場合は logged_in_at が含まれます。
インスタンスが受け付けなくなった保存済みのキー(たとえば Studio で削除したキー)は削除されません。エラーには、それを置き換える login が示されます。
ironflock logout
インスタンスの保存済みのキーを削除します。ほかのインスタンスのログインは残ります。
ironflock logout [--instance <domain or URL>]$ ironflock logout --instance factory.example.com
Logged out of https://api.factory.example.com: its key is removed from /home/operator/.config/ironflock/credentials.json. The key itself stays valid until it is deleted in Studio.logout はどのインスタンスとも通信しません。キーは、Studio で削除するまで有効なままです。保存済みのログインがなくてもエラーではありません。コマンドはその旨を表示し、終了コード 0 で終了します。IRONFLOCK_API_KEY が設定されている場合は、コマンドが引き続きこの変数を使うことを注記で示します。
ironflock device create
プロジェクトにデバイスを作成し、デバイスの認証情報を含むデバイスの .flock ファイルを書き込みます。
ironflock device create --project <project> --name <name> -o <file.flock> [flags]$ ironflock device create --project 12 --name press-7 -o press-7.flock
Created the device press-7 (key 345) in the project Packaging (key 12). Its .flock is in press-7.flock: it holds the device's credentials, which the platform shows no more. 'sudo ironflock agent install -c press-7.flock' connects a machine as this device.動作環境: Linux、macOS、Windows。root: 不要。必要なもの: スコープ devices:write を持つキー。名前で指定したプロジェクトは devices:read で検索されます。
| フラグ | 意味 |
|---|---|
--project <project> | 必須。プロジェクトのキーまたは名前 |
--name <name> | 必須。デバイスの名前。英字、数字、ドット、アンダースコア、ハイフンで 1~100 文字。プロジェクトに同じ名前のデバイスがまだないこと |
-o, --output <file> | 必須。.flock を書き込むファイル(名前は *.flock)、または標準出力を表す - |
--description <text> | 最大 2000 文字 |
--wifi-ssid <name> | デバイスの Wi-Fi ネットワーク。--wifi-password-file と一緒に指定します |
--wifi-password-file <file> | ネットワークのパスフレーズを含むファイルまたはパイプ。--wifi-ssid と一緒に指定します |
--force | -o のファイルが存在する場合に置き換える |
--instance, --ca-cert | whoami と同じ |
- 名前で指定したプロジェクト は、キーが操作できるプロジェクトの中から検索され、ちょうど 1 つのプロジェクトの名前である必要があります。どのプロジェクトの名前でもない場合は終了コード 1 です。複数のプロジェクトの名前である場合は終了コード 2 で、メッセージにそれらのキーが示されます。
.flockファイルは最初のバイトから非公開です。モード 0600、Windows ではあなただけにアクセスを許可するアクセスリストです。既存のファイルは--forceなしでは置き換えられません。また、フォルダーと名前はデバイスを作成する前にチェックされます。API が認証情報を返すのは、デバイスを作成したときだけだからです。FAT でフォーマットした USB スティックなど、ファイルモードのないファイルシステムでは、ファイルは非公開になりません。マシンのディスクに書き込み、そこからコピーしてください。-o -はファイルを標準出力に書き込みます。標準出力は端末であってはなりません。たとえば、ファイルをパイプで別のマシンに渡す場合に使います。このとき、結果の行は標準エラー出力に出力されます。- ファイルの内容は何も表示されません。結果には、デバイスのキーと名前、およびプロジェクトが示されます。
- デバイスの作成後に何かが失敗した場合、エラーはその旨を示し、デバイスを削除するコマンドを示します。
このファイルでマシンを接続するには デバイスエージェントのコマンド の説明に従うか、os flash でドライブに書き込みます。
ironflock device list
アカウントが権限を持つデバイスを、キーが操作できるプロジェクトの範囲で一覧表示します。
ironflock device list [--project <project>] [--instance <instance>] [--ca-cert <file>]...$ ironflock device list --project Packaging
KEY NAME PROJECT STATUS ARCHITECTURE AGENT
17 press-7 12 CONNECTED amd64 1.4.2
18 press-8 12 CONFIGURING amd64 -必要なもの: スコープ devices:read を持つキー。--project を指定すると、1 つのプロジェクトのデバイスだけを表示します。デバイスがなくてもエラーではありません。コマンドは No devices. と表示します。--json では、結果に instance と devices が含まれ、各デバイスには device_key、name、project_key、description、status、architecture、agent_version があります。レスポンスから読み取るのはこれらのフィールドだけです。デバイスの認証情報がこれらに含まれることはありません。
ironflock device delete
プロジェクトからデバイスを削除します。削除したデバイスは元に戻せません。
ironflock device delete --project <project> <device_key> [--yes] [--instance <instance>] [--ca-cert <file>]...$ ironflock device delete --project Packaging 17
This deletes the device 17 from the project Packaging (key 12) of https://api.ironflock.com. A deleted device cannot be brought back.
Delete the device 17? [y/N]
Deleted the device press-7 (key 17) from the project 12.必要なもの: スコープ devices:write を持つキー。デバイスのキーが唯一の引数です。コマンドは何が削除されるかを示し、No を既定として質問します。--yes は yes と答えます。端末がない場合と --json では何も質問せず、--yes を指定しない限り終了コード 4 で終了します。このとき、何も削除されません。プロジェクトにないデバイス、またはキーから見えないデバイスは 404 です。
--project と --name で新しいデバイスをインストールする
ironflock agent install、ironflock os flash、ironflock os install は、-c <device.flock> の代わりに --project <project> --name <name> を受け付けます。コマンドはデバイスを作成し、プラットフォームが送る .flock を使って、-c のファイルの場合とまったく同じように処理を続けます。.flock はメモリ上に保持され、あなたが管理する必要のあるファイルには保存されません。
sudo ironflock agent install --project Packaging --name press-9 --yes
ironflock os flash --project 12 --name cell-4 -d /dev/sdb
ironflock --host admin@machine os install --project 12 --name cell-4 --disk /dev/sda --yes --wait-online| フラグ | 意味 |
|---|---|
--project <project> | デバイスを作成するプロジェクト。device create と同じく、キーまたは名前 |
--name <name> | 新しいデバイスの名前。device create と同じ |
--instance <instance> | インスタンス。whoami と同じ |
--ca-cert <file> | agent install:インスタンスの証明書の認証局。os flash と os install には、デバイス用の独自の --ca-cert があります。--project と併用すると、それはインスタンスに対しても信頼されます |
--wait-online[=<duration>] | --host 経由の os install のみ:そこでのコマンドの後、プラットフォームがデバイスをオンラインと認識するまで、指定した時間(1 分~2 時間。値なしでは 15 分)待ちます。値は --wait-online=20m のように = の後に続けます |
--projectと--nameは一緒に指定し、-cとは併用できません。agent installとos flashには、2 つのうちどちらかが必要です。os installは、どちらもない場合、従来どおりインストール済みのエージェントの.flockを使います。--projectと--dry-runの併用は拒否されます。ドライランでは何も作成されないためです。- キーは
whoamiと同じです。IRONFLOCK_API_KEY、なければ保存済みのログインです。sudoで実行したコマンドは root として動作し、root のログインを探します。キーはsudo --preserve-env=IRONFLOCK_API_KEYで渡すか、自分のマシンから--hostでコマンドを実行してください。--hostでは、プラットフォームへの問い合わせは自分のマシンから行われ、対象のマシンが受け取るのは.flockだけです。キー、認証情報ファイル、IRONFLOCK_API_KEYが対象のマシンに届くことはありません。 - プラットフォームがデバイスの
.flockを渡すのは、デバイスを作成する応答の中だけです。そのため、プロジェクトにすでにある名前は拒否されます(終了コード 1)。そのデバイスは、その.flockと-cでインストールするか、先にdevice deleteで削除してください。 - デバイスの作成後にいずれかの手順が失敗した場合、エラーはその旨を示し、デバイスを削除する
device deleteコマンドを示します。それを実行してから、同じコマンドをもう一度実行してください。
エラー
失敗すると、終了コード 1 と 1 つの文で終了します。インスタンスの文はステータスの後に続きます。
| 応答 | 文の内容 |
|---|---|
| 到達できない、証明書が信頼されていない | インスタンスに到達できないこと。--ca-cert のヒント付き |
400 | インスタンスがリクエストを拒否したことと、その理由 |
401 | インスタンスがキーを受け付けないことと、キーの出どころ。保存済みのキーの場合は、それを置き換える login |
403 | キーにはこの操作ができないこと。スコープ、またはキーが限定されているプロジェクトやアプリが許可していません。whoami でそれらを確認できます |
404 | delete の場合:デバイスがプロジェクトにない、またはキーから見えない。create の場合:このキーにとってプロジェクトが存在しない |
409 | プラットフォームが保持しているものとの競合。たとえば、プロジェクトにすでにあるデバイス名 |
500、503、504 | プラットフォームが利用できないこと。create と delete では、変更が行われた可能性があることと、それを確認する device list も示します |
リクエストの書き込み後に失敗した場合、および create や delete の待機中に Ctrl-C を押した場合、メッセージは変更が行われた可能性があることを示します。繰り返す前に ironflock device list を実行してください。同じ名前での 2 回目の create は競合になり、API が最初のデバイスの認証情報を再度返すことはありません(Studio では設定ファイルをダウンロードできます)。
終了コード
これらのコマンドは、すべてのコマンドに共通する 終了コード を使います。
| コード | ここでの意味 |
|---|---|
| 0 | 完了 |
| 1 | インスタンスまたはプラットフォームが拒否した、または失敗した。プロジェクト名がどのプロジェクトの名前でもない。またはファイルを書き込めなかった |
| 2 | コマンドラインの誤り:フラグがない、または誤っている、複数のプロジェクトの名前であるプロジェクト名、--force なしの既存ファイル、--host または --hosts。プラットフォームには問い合わせていません |
| 3 | ログインがない:IRONFLOCK_API_KEY が設定されておらず、保存済みのログインもない。または認証情報ファイルが使えない。プラットフォームには問い合わせていません |
| 4 | device delete の質問に no と答えた、または質問できず --yes が指定されていなかった。何も削除されていません |
| 130 | プラットフォームへの問い合わせ中に中断された。変更が行われた可能性があります |