Skip to Content
IoT 앱 개발IronFlock CLI로그인 및 디바이스 관리

로그인 및 디바이스 관리

이 명령들은 명령이 실행되는 머신 대신 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.comhttps://api.ironflock.com
어플라이언스의 도메인 factory.example.comhttps://api.factory.example.com
Studio를 열 때 쓰는 주소 https://factory.example.com/projects/12https://api.factory.example.com
API 자체의 호스트 api.factory.example.comhttps://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\입니다. 이 파일에는 인스턴스마다 항목이 하나씩 있으며, 본인만 읽을 수 있습니다. 다른 사람이 읽거나 변경할 수 있는 파일이나 폴더는 사용되지 않습니다. 명령은 종료 코드 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을 담은 객체 하나입니다.

본인만 읽을 수 있는 파일에 키를 넣은 다음 로그인하십시오:

(umask 077; cat > key.txt) ironflock login --key-file key.txt

cat > 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-certwhoami와 같음
  • 이름으로 지정한 프로젝트는 키로 작업할 수 있는 프로젝트에서 조회하며, 정확히 한 프로젝트의 이름이어야 합니다. 어떤 프로젝트의 이름도 아니면 종료 코드 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는 한 프로젝트의 디바이스만 남깁니다. 디바이스가 없어도 오류가 아닙니다. 명령은 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는 예로 답합니다. 터미널이 없거나 --json을 사용하면 아무것도 묻지 않으며, --yes가 지정되지 않으면 종료 코드 4로 끝납니다. 이때는 아무것도 삭제되지 않습니다. 프로젝트에 없거나 키가 볼 수 없는 디바이스는 404입니다.

--project와 --name으로 새 디바이스 설치

ironflock agent install, ironflock os flash, ironflock os install은 -c <device.flock> 대신 --project <project> --name <name>을 받습니다. 명령은 디바이스를 생성하고, -c의 파일로 진행할 때와 똑같이 플랫폼이 보내 준 .flock으로 진행합니다. .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에는 둘 중 하나가 필요합니다. 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과 함께 한 문장이 출력됩니다. 인스턴스의 문장은 상태 코드 뒤에 옵니다.

응답문장의 내용
도달할 수 없음, 인증서를 신뢰할 수 없음인스턴스에 도달할 수 없다는 것과 --ca-cert에 대한 힌트
400인스턴스가 요청을 거부했다는 것과 그 이유
401인스턴스가 키를 받지 않는다는 것과 키의 출처. 저장된 키의 경우 이를 대체할 login
403키가 이 작업을 할 수 없다는 것: 키의 스코프나, 키가 제한된 프로젝트 또는 앱이 이를 허용하지 않습니다. whoami가 이를 보여 줍니다
404delete의 경우: 디바이스가 프로젝트에 없거나 키가 볼 수 없다는 것. create의 경우: 이 키에 대해 프로젝트가 존재하지 않는다는 것
409프로젝트에 이미 있는 디바이스 이름처럼, 플랫폼이 가진 것과의 충돌
500, 503, 504플랫폼을 사용할 수 없다는 것. create와 delete의 경우 변경이 이루어졌을 수 있다는 것과 이를 보여 주는 device list도 함께

요청을 보낸 뒤의 모든 실패, 그리고 create나 delete가 기다리는 동안 누른 Ctrl-C 뒤에는 변경이 이루어졌을 수 있다는 메시지가 나옵니다. 다시 실행하기 전에 ironflock device list를 실행하십시오. 같은 이름으로 두 번째 create를 하면 충돌이며, API는 첫 번째 디바이스의 자격 증명을 다시 반환하지 않습니다(Studio에서 그 구성 파일을 다운로드할 수 있습니다).

종료 코드

이 명령들은 모든 명령에 공통인 종료 코드를 사용합니다.

코드여기서의 의미
0완료
1인스턴스나 플랫폼이 거부했거나 실패함, 어떤 프로젝트의 이름도 아닌 프로젝트 이름, 또는 파일을 쓸 수 없음
2명령줄이 잘못됨: 누락되거나 잘못된 플래그, 여러 프로젝트의 이름인 프로젝트 이름, --force 없이 지정한 기존 파일, --host 또는 --hosts. 플랫폼에 요청하지 않았습니다
3로그인 없음: IRONFLOCK_API_KEY가 설정되어 있지 않고 저장된 로그인도 없음. 또는 자격 증명 파일을 사용할 수 없음. 플랫폼에 요청하지 않았습니다
4device delete의 질문에 아니요로 답했거나, 질문할 수 없는데 --yes가 지정되지 않음. 아무것도 삭제되지 않았습니다
130플랫폼에 요청하는 동안 중단됨. 변경이 이루어졌을 수 있습니다
Last updated on