디바이스 에이전트 명령

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은 디바이스 하나를 지정하므로 agent configure는 -c를 받지 않습니다. agent install은 한 번에 머신 하나에서만 실행됩니다.

설치된 에이전트의 구성 요소

에이전트는 시작할 때마다 호스트의 몇 가지 설정도 직접 씁니다. 에이전트가 실행되며 에이전트용 메모리를 확보해 두는 슬라이스 ironflock.slice, systemd 워치독, 커널의 크래시 설정, 저널 크기 상한입니다.

이전 IronFlock 설치 프로그램이 설정한 머신에서는 에이전트가 아직 legacy 구성 /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 — 미러가 제공하지 않는 파일은 각각 클라우드에서 가져옵니다. 미러의 파일이 검사(체크섬, 서명)를 통과하지 못하면 세 파일 모두 클라우드에서 가져옵니다.

대체할 때마다 stderr에 미러, 파일, 이유가 담긴 Warning: ... 줄이 나오며, --json을 사용하면 결과의 warnings에 항목이 추가됩니다. 미러도 클라우드도 파일을 제공하지 않으면 설치는 두 출처와 두 이유를 모두 알려 주는 오류 하나로 실패합니다(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에 대해, 설치에 지정한 다운로드 베이스와 프록시 플래그로 실행됩니다.

그중 네 검사는 실패하면 설치를 중단합니다. 그대로 진행하면 설치가 확실히 실패하거나 도중에 실패하기 때문입니다:

메시지에는 검사, 그 진단 내용, 힌트가 나옵니다. 그 밖의 모든 진단 내용은 stderr의 경고이며 설치는 계속됩니다. 네트워크가 허용하는 즉시 에이전트가 연결하고, 업데이트하고, 앱을 가져옵니다. warning 또는 skipped 결과는 설치를 중단하지 않습니다. 설치하기 전에 모든 검사를 보려면 ironflock doctor -c device.flock을 실행하십시오.

단계

1. 설치할 패키지를 알리고 묻습니다. apt로 설치합니다.
2. 머신에 Docker가 없으면 먼저 묻고 Docker를 설치합니다.
3. 프로덕션 채널의 에이전트를 다운로드하고 체크섬과 서명으로 확인합니다. 확인된 에이전트를 받을 수 없는 설치는 다음 단계를 하나도 실행하지 않고 여기서 중단됩니다.
4. 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을 되풀이하지 않습니다. 비밀번호를 파일에 한 줄로 쓰거나, --proxy-password-file /dev/stdin으로 파이프를 통해 전달하십시오(시크릿).

--no-proxy의 호스트 외에 다음 호스트도 프록시를 거치지 않습니다(NO_PROXY): localhost, 127.0.0.1, ::1, 그리고 다운로드 서버와 .flock의 업데이트 서버(update_url)가 LAN의 어플라이언스나 미러처럼 IronFlock 클라우드의 호스트가 아닐 때 그 서버. 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: 줄이 알리는 대로, 파일마다 항목 하나입니다.

거부하는 경우

잘못된 명령줄은 아무것도 실행되기 전에 종료 코드 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 설치 USB 스틱에서는 스틱이 디바이스가 아니라고 알려 줍니다.
• 에이전트가 이미 설치된 경우. legacy 구성 /opt/reagent에 설치된 경우도 포함합니다. 메시지는 agent configure와 agent remove를 알려 줍니다.
• 에이전트가 머신을 legacy 구성에서 옮기는 중인 경우
• 이전 설치가 에이전트를 설정하기 전에 중단되었고, 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에 그 사실을 알리는 줄이 나옵니다. 예: 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을 지정하지 않으면 디바이스 설정의 URL 중 사용자를 지정한 URL에 들어가므로, 파일만으로 새 비밀번호를 설정할 수 있습니다.
• --no-proxy, 그리고 프록시가 없던 디바이스의 첫 프록시에는 localhost, 127.0.0.1, ::1도 들어가며, 에이전트 .flock의 업데이트 서버가 IronFlock 클라우드의 호스트가 아니면(어플라이언스의 서버) 그 서버도 들어갑니다.
• --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를 알려 줍니다. 다시 실행하면 설정이 이미 적용되어 있으므로 아무것도 재시작하지 않습니다.
• 설정을 쓸 수 없으면 아무것도 재시작되지 않으며, 오류는 명령을 다시 실행하라고 알려 줍니다.

이전 설치는 프록시 설정을 http-proxy.conf 드롭인의 Environment= 줄에 썼으며, 그곳에서는 모든 사용자가 systemctl show로 비밀번호까지 읽을 수 있습니다. 이 설정은 -c만 지정한 실행을 포함해 agent configure를 어떻게 실행하든 /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가 아직 등록되지 않은 디바이스를 등록합니다.
• 에이전트가 머신을 legacy 구성에서 옮기는 중인 경우
• 프록시 플래그를 지정했는데 에이전트가 아직 legacy 구성 /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 설치 USB 스틱에서 명령을 실행한 경우
• 시스템에 /usr/lib/ironflock/image.json이 없거나, 에이전트가 legacy 구성에 있는 경우

ironflock agent update

에이전트가 자신의 채널 릴리스로 자체 업데이트하게 하고, 그 과정을 추적합니다. 에이전트는 시작할 때마다 더 새로운 릴리스를 찾습니다. 명령은 에이전트를 재시작하고 결과를 알려 줍니다. 디바이스는 잠시 IronFlock에서 오프라인이 되며, 앱은 계속 실행됩니다.

ironflock agent update [flags]

실행 환경: 에이전트가 설치된 Linux. root 권한: 필요. 질문: 예. 재시작이 무엇을 하는지 알린 뒤 묻습니다. --yes로 답합니다.

이 명령에는 자체 플래그가 없으며 버전을 받지 않습니다. 에이전트는 자신의 업데이트 서버에서 자신의 채널(production, IronFlock 테스트 플랫폼에서는 test)을 따릅니다. 업데이트 서버는 .flock의 update_url(어플라이언스의 미러), 없으면 IronFlock 클라우드입니다. --download-base는 이를 바꾸지 않습니다.

에이전트는 다음 순서로 동작합니다:

1. 자신의 채널 릴리스를 읽습니다. 이 디바이스에서 두 번 실패한 릴리스는 더 새로운 릴리스가 나올 때까지 다시 다운로드하지 않습니다.
2. 더 새로운 릴리스를 자신의 폴더에 다운로드하고 서명을 확인합니다.
3. 다운로드 10초 후 새 버전을 제자리에 두고 새 버전으로 재시작합니다. IronFlock에 마지막으로 연결된 시점이 12분 전에서 하루 전 사이이면 업데이트를 보류합니다. 업데이트는 연결된다고 확인된 버전에서만 활성화됩니다.
4. 새 버전은 검증 기간에 들어갑니다. 시작 후 10분 안에 IronFlock에 연결하고 2분 동안 실행 상태를 유지해야 합니다. 그렇지 못하거나 그 전에 세 번 멈추면 에이전트는 이전 버전으로 돌아갑니다.
5. 롤백 후에는 이전 버전이 연결해야 합니다. 그러면 새 버전에 문제가 있었던 것입니다. 새 버전은 다음 업데이트 때 한 번 더 시도되며, 두 번째로 실패하면 더 새로운 릴리스가 나올 때까지 차단됩니다. 이전 버전도 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"}

거부하는 경우

명령은 다음 경우에 종료 코드 3으로 거부합니다: 에이전트가 설치되어 있지 않을 때(메시지는 agent install을 알려 줌), 에이전트가 머신을 legacy 구성에서 옮기는 중일 때, 에이전트가 legacy 구성에서 실행 중일 때(이 구성의 업데이트는 명령이 추적할 수 있는 상태를 남기지 않음), 그리고 에이전트가 1.3.0보다 오래된 버전일 때(1.3.0은 자신의 유닛 아래에서 자체 업데이트하는 첫 버전입니다).

재시작이 실패하거나, 업데이트가 에이전트의 제한 시간 안에 진행되지 않으면 어디를 확인해야 하는지 알려 주는 오류와 함께 종료 코드 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가 없거나 실패해도 제거는 중단되지 않으며, 어떤 로그인이 제거되지 않았는지 알려 주는 줄이 나옵니다.

호스트가 직접 둔 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"]}

거부하는 경우

에이전트가 설치되어 있지 않을 때, 그리고 에이전트가 머신을 legacy 구성에서 옮기는 중일 때 명령은 종료 코드 3으로 거부합니다. IronFlockOS에서는 root 여부와 관계없이 다른 무엇보다 먼저 거부합니다. 이미지가 시스템과 함께 에이전트를 제공하며, 모든 OS 업데이트와 다음 등록이 에이전트를 다시 설정하기 때문입니다. 메시지는 ironflock os reset을 알려 줍니다. 이 명령은 디바이스를 IronFlock에서의 ID가 없는, 새로 쓴 IronFlockOS 상태로 되돌립니다. IronFlockOS 설치 USB 스틱에서는 스틱이 디바이스가 아니라고 알려 줍니다.

아니요라고 답하거나, 터미널도 --yes도 없이 질문하게 되면 명령은 종료 코드 4로 끝납니다.

ironflock agent restart

에이전트의 서비스를 재시작하고 에이전트가 다시 실행되는지 확인합니다. 유닛이 하나의 프로세스로 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>을 알려 줌), 에이전트가 머신을 legacy 구성에서 옮기는 중일 때, systemd가 에이전트의 유닛을 모를 때(메시지는 agent remove를 알려 줌) 종료 코드 3으로 거부합니다.

실패: 에이전트가 올라오지 않으면 종료 코드 1로 실패합니다. systemd가 유닛을 시작할 수 없거나, 프로세스가 5초 안에 끝나는 경우입니다. 오류는 유닛과, 마지막 로그 줄이 있는 곳을 알려 줍니다: 에이전트의 로그(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와 마찬가지로 에이전트가 올라오는지 확인합니다. 유닛이 하나의 프로세스로 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와 같습니다. 에이전트가 설치되어 있지 않을 때, 에이전트가 머신을 legacy 구성에서 옮기는 중일 때, 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로 바꾸고 새 로그를 시작하며, 이런 파일을 두 개까지 보관합니다. 명령은 로그와 이 파일들을 읽습니다.

에이전트는 한 줄에 JSON 객체 하나를 씁니다: 항목의 시각(초 단위), 레벨, 메시지, 그 밖의 필드. 텍스트 형식은 IronFlock Studio가 에이전트의 로그를 보여 주는 것처럼 항목을 표시합니다: UTC 시각, 레벨, 메시지와 그 오류. 크래시의 스택 트레이스처럼 항목이 아닌 줄은 그대로 표시됩니다. 제어 문자는 이스케이프되므로(\n, \x1b) 항목은 터미널에서 한 줄이며 터미널을 조작할 수 없습니다. --json을 사용하면 각 줄은 stdout의 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으로, 한 줄에 객체 하나씩
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으로 거부합니다.