crew 명령

crew은 하나의 lead 아래에서 Collie를 실행하는 여러 대의 머신이며, 휴대폰은 lead의 단일 URL을 통해 모든 머신의 herd에 접근합니다. lead는 휴대폰이 연결되는 머신이고, 다른 모든 머신은 member이며, deputy는 인계를 받을 수 있도록 허용된 단 하나의 member입니다.

collie join 및 collie leave은(는) 여전히 작동합니다. 동일한 인수와 종료 코드를 사용하는 collie crew join 및 collie crew leave의 별칭입니다.

collie pack 역시 이 표의 모든 동사에서 계속 작동합니다. 이는 동일한 인수와 종료 코드를 갖는 collie crew의 별칭입니다. collie docs pack은(는) 이 페이지를 출력하며 웹 앱의 /pack 주소는 /crew로 리디렉션됩니다. 세 가지 모두 2.0.0(ADR 0038)에서 제거됩니다.

deputy, approve-promote, promote 명령은 장애 조치를 관리합니다. 설정 및 복구 지침은 docs/deployment.md → 대기 도어 및 비상 시을(를) 참조하십시오.

두 대의 머신, 하나의 crew

머신을 추가하는 명령은 Herdr용과 Collie용 두 가지가 있으며, crew add이 SSH로 접속할 수 없는 호스트 및 일반 HTTP를 제공하는 lead를 위한 수동 경로도 제공됩니다.

herdr machine add --label <name> <ssh-target>   # prepare the remote host
collie crew add <ssh-host>                      # install Collie there and enroll it

herdr machine add은 현재 사용 중인 머신에서 실행됩니다. 원격 호스트에 Herdr를 설치하고 Herdr 자체 목록에 저장하지만, 머신을 crew에 추가하지는 않습니다. collie crew add은 lead에서 실행됩니다. <ssh-target>와 <ssh-host>은 동일한 호스트이며, user@host 또는 ~/.ssh/config에 정의된 Host 별칭으로 작성되고, <name>은 Herdr 목록의 레이블로만 사용됩니다.

collie crew add <ssh-host>은 사용자의 ssh를 통해 원격 호스트에 Collie를 설치하고 등록합니다. 로컬에서 토큰을 생성하고, 원격 머신에 Collie를 프로비저닝한 다음, 해당 머신에서 collie crew join을 실행합니다. 이 명령은 herdr machine add이 설치하는 원격 호스트에 사전 설치된 Herdr를 필요로 하므로, 두 명령은 함께 사용됩니다. 일반 HTTP를 제공하는 lead는 crew add가 --insecure를 지원하지 않으므로 수동으로 한 단계를 더 수행해야 합니다. 참가하는 머신에서 collie crew join --insecure을 실행하십시오. 특정 호스트에 대해 crew add 또는 수동 경로 중 하나만 사용하고, 둘 다 사용하지는 마십시오. 대상 없이 collie crew add을 실행하면 ssh 설정과 Herdr가 이미 알고 있는 호스트 목록이 각 이름이 확인되는 호스트 기준으로 병합되어 표시되므로, 호스트를 다른 방식으로 입력하기보다는 해당 목록에서 선택하십시오(아래).

crew add은 자체 설치 유형이 지정하는 경로를 따릅니다. Herdr 플러그인 설치와 같이 git 체크아웃에서 실행되는 lead는 자체 커밋을 멤버에 푸시하고 거기서 빌드하므로 해당 멤버에는 git 및 Bun이 필요합니다. 독립 실행형 설치 또는 패키지에서 가져온 lead에는 커밋이 없으므로, 자체 실행 중인 릴리스로부터 동일한 SSH를 통해 전송된 Collie 자체 설치 프로그램을 사용하여 멤버를 설치하며, 이 경우 해당 멤버에는 curl, tar 및 sha256sum 또는 shasum이 필요합니다. --path은 첫 번째 경로에서는 원격 체크아웃을, 두 번째 경로에서는 설치 루트를 지정합니다. 이미 다른 유형의 설치를 실행 중인 멤버는 덮어쓰지 않고 거부되며, 거부 메시지에는 이를 해결하는 단일 명령이 표시됩니다. 두 번째 경로에서 멤버는 github.com에서 직접 릴리스를 다운로드하므로, github.com으로 가는 경로가 없는 멤버는 체크아웃에서 실행되는 lead가 필요합니다.

터미널 collie crew update은 동일한 두 경로를 사용하며, 동일한 사실을 확인하여 하나를 선택합니다. 체크아웃 lead는 자체 커밋을 각 멤버에 푸시하고, 독립 실행형 설치 또는 패키지의 lead는 각 멤버를 자체 실행 중인 릴리스 수준으로 맞춥니다. 릴리스 lead에서는 git 체크아웃에서 실행 중인 멤버를 건너뛰며, 해당 머신에서 실행할 명령인 collie update --to-tag v<version>이 해당 행에 표시됩니다. 체크아웃 lead에서는 install.sh로 설치된 멤버를 반대 방식으로 건너뜁니다. 릴리스를 수신하므로 휴대폰의 Updates 페이지에서 수준을 맞춥니다. 건너뛴 멤버가 있어도 실행이 중단되지 않으며, 확인 프롬프트에서 별도로 집계됩니다.

수동 경로는 네 개의 명령으로 구성됩니다. SSH로 연결할 수 없는 호스트나 일반 HTTP를 제공하는 lead에 사용하십시오. lead의 설치 유형 때문이 아니며, 모든 유형의 lead가 crew add을 통해 멤버를 추가합니다. lead는 휴대폰에서 이미 연결 가능한 인스턴스이며, 참여하는 머신에는 Collie가 설치되어 실행 중이어야 합니다.

1. 01
   lead에서 토큰을 생성하십시오.

   collie crew invite        # prints the token, then the join command to run

   토큰은 한 줄입니다: <token>.<lead-fingerprint>.

1. 01
   참가하는 머신에서 crew에 참가하고 메시지가 나타나면 토큰을 붙여넣으십시오.

   collie crew join https://lead.tail1234.ts.net

   invite 출력에서 주소를 복사하십시오. 이 예시가 아니라 사용자의 lead 자체 주소입니다.

1. 01
   실행 중인 프로세스가 새 member를 인식할 수 있도록 lead를 재시작하십시오.

   collie restart

1. 01
   lead에서 링크가 응답했는지 확인하십시오.

   collie crew status        # the new member, its address, and whether the link answered

토큰은 1회용이며, 10분간 유효하고, 한 번만 표시됩니다. lead는 해시만 저장합니다. invite을 실행하면 들어오는 등록을 수락할 수 있도록 lead 프로세스가 재시작되고, lead 이름이 포함된 join 명령 줄이 출력됩니다.

3단계는 두 번째 재시작이며, join이 완료될 때 이를 안내합니다. invite은 등록을 수락할 수 있도록 lead를 재시작했습니다. 그 후 join가 새 member를 디스크에 기록했으며, 실행 중인 프로세스는 다시 재시작될 때까지 해당 member로 트래픽을 프록시하지 않습니다.

대화형 터미널에서 join은 토큰을 입력하라는 메시지를 표시합니다. 스크립트에서는 -을 전달하고 stdin으로 토큰을 제공하십시오.

collie crew join https://lead.tail1234.ts.net -   # paste the token on stdin

디스크에서 토큰을 읽으려면 대신 @<file>을 전달하십시오. 원시 토큰을 인수로 직접 전달하면 경고가 출력됩니다. 프로세스 목록을 통해 모든 로컬 사용자에게 인수가 노출되기 때문입니다(CREW_PROTOCOL.md §8.3).

lead 주소를 이 노드에서 접근할 수 있는 호스트 이름 또는 host:port(으)로 설정하십시오. 스킴과 포트가 없는 주소는 Collie 자체 리스너가 바인딩되는 포트인 https://<host>:8787(으)로 해석됩니다.

crew invite에 출력되는 내용은 lead가 게시되는 방식에 따라 달라집니다. 기본 HTTPS 모드에서 lead는 루프백을 수신 대기하고 tailscale serve이(가) 이를 포트 443에 게시합니다. 따라서 invite은(는) 포트 443으로 연결하는 https://<full-tailnet-name>을(를) 출력합니다. COLLIE_SERVE_PORT(으)로 진입점을 옮긴 경우 <name>:<port>을(를) 출력합니다. COLLIE_SERVE_MODE=http을(를) 사용하면 lead 자체 리스너가 일반 HTTP를 통해 포트 8787에서 응답하며, invite은(는) 포트를 변경한 경우에만 포트를 포함하여 짧은 이름을 출력합니다. join은(는) 일반 HTTP를 통해 토큰을 보내기 전에 한 번 확인을 요청하며, --insecure은(는) 이를 자동으로 승인합니다. 명시적인 http:// 주소에는 여전히 --insecure이(가) 필요하며 아무것도 확인을 요청하지 않습니다.

crew add은(는) member에게 동일한 진입점을 전달하므로 member 또한 포트 443으로 연결합니다. 이름만 지정하면 포트 8787을 의미하게 되지만, tailscale serve 뒤에 있는 lead는 이 포트를 tailnet에 개방하지 않습니다.

crew join의 --address은(는) lead가 이 머신에 연결할 때 사용하는 주소이며, 포트가 필요합니다: --address <host>:8787. 포트가 없는 주소는 lead가 포트 443으로 연결을 시도하게 되므로 join이(가) 거부합니다. https://host:8787 주소는 그대로 허용되어 host:8787(으)로 저장됩니다.

멀티플렉서 선택은 각 노드마다 로컬로 적용됩니다. 해당 노드의 자체 .env에서 COLLIE_MUX을(를) 구성하십시오. 바이너리 설치의 경우 ~/.config/collie/.env에, Herdr 설치의 경우 Herdr의 플러그인 설정 디렉터리에 있습니다. 머신 간 회선인 crew 프로토콜에는 멀티플렉서 전용 필드가 포함되지 않습니다. 피어는 v1(CREW_PROTOCOL.md §16)에서 Herdr로만 테스트되었음에 유의하십시오.

멤버가 항상 자체적으로 결정할 수는 없으므로 crew add이 새 멤버에 대해 해당 값을 확정합니다. 정확히 하나의 멀티플렉서를 실행 중인 멤버는 그대로 두고, 자체 첫 시작 시 해당 멀티플렉서를 선택합니다. 여러 개를 실행 중인 멤버의 경우 lead가 사용자에게 질문하며, 사용자의 답변은 해당 멤버의 .env에 COLLIE_MUX로 기록됩니다. 이미 이름을 지정한 멤버도 그대로 둡니다. 미리 답변하거나 멤버가 이미 보유한 이름을 바꾸려면 --mux <name>을 전달하십시오. 실행 중인 멀티플렉서가 없는 멤버는 경고를 받고 아무것도 기록되지 않습니다. 멀티플렉서가 실행될 때까지 첫 시작이 거부되기 때문입니다.

Herdr 머신 및 crew

Herdr의 저장된 머신 목록과 Collie crew는 별개의 목록이며, 서로 연동되지 않습니다.

머신을 추가하려면 위의 두 대의 머신, 하나의 crew을 참조하십시오.

Herdr의 머신 목록은 사용자의 Herdr 창에 종속됩니다. Herdr 0.9.0은 저장된 SSH 대상을 클라이언트에 유지하며 사용할 때마다 SSH를 통해 각 대상에 접속합니다. 현재 사용 중인 머신의 해당 창에서 대상 머신들의 터미널을 사용할 수 있습니다.

crew는 모든 머신에 설치된 Collie이며, lead는 사용자의 ssh를 통해 한 번 설정된 Collie 자체 암호화 링크를 통해 각 member에 접근합니다. crew는 터미널도 표시하며, 터미널 이상의 기능을 수행합니다. 업로드를 전송합니다. 각 머신의 저널과 감사 로그를 해당 창을 실행한 머신에 유지합니다. 휴대폰에서 한 번 확인하는 것만으로 전체 crew를 업데이트합니다. lead가 응답하지 않을 때 프런트 도어를 deputy에 넘길 수 있습니다. 머신 목록이 전혀 없는 tmux 및 zellij 환경에서도 동일하게 작동합니다.

세 가지 사실로 인해 두 목록이 분리되어 유지되며, 각각이 독립적인 이유가 됩니다.

휴대폰은 ssh 키를 절대 보관하지 않습니다. ssh 키는 머신에 대한 전체 셸 권한을 의미하며, 휴대폰은 분실될 수 있습니다. 대신 휴대폰은 lead가 발급한 페어링 코드를 보관하며, 이 코드는 앱만 열 수 있고 다른 권한은 없습니다. 또한 collie devices revoke <label>을 사용하면 재시작 없이 해당 코드를 즉시 폐기할 수 있습니다(기기 페어링).

업로드, 저널 및 감사 로그는 해당 창을 실행하는 머신에 저장됩니다. 그리고 두 머신 사이의 암호화된 통신선을 뜻하는 crew 링크는 member가 등록된 후에는 ssh가 필요하지 않습니다.

따라서 동일한 설정을 두 번 반복할 필요가 없습니다. SSH를 한 번 설정하면 두 도구가 모두 이를 사용합니다. Herdr는 자체 창을 위한 목록을 유지하고, Collie는 휴대폰을 위한 crew를 유지합니다. Herdr에 머신을 추가해도 crew에는 추가되지 않습니다. Herdr에서 머신을 제거해도 crew에서 제거되지 않습니다. tmux나 zellij를 실행하는 crew 구성원은 Herdr 목록에 나타나지 않습니다.

대상 없이 collie crew add을(를) 실행하면 두 목록의 후보를 모두 표시하므로 호스트를 두 번 입력할 필요가 없습니다. ~/.ssh/config의 Host 항목을 읽고 herdr machine list --json을(를) 실행합니다. 각 이름이 확인되는 ssh 대상을 기준으로 두 목록을 병합합니다. 이 명령은 해당 설정 내의 Include을(를) 1단계 깊이까지만 따르며, ~/.ssh/ 하위 경로에 대해서만 동작합니다. 포함된 파일 안에서 다시 포함된 파일의 별칭은 제공하지 않습니다. 각 행에는 이름의 출처(ssh config, herdr 또는 둘 다)가 표시됩니다. 이미 이 crew에 속한 머신의 행에는 번호 대신 해당 구성원의 id가 표시됩니다.

crew 연결 방식

lead만 프런트 도어를 노출하고, crew의 다른 모든 머신은 프런트 도어를 노출하지 않습니다.

lead는 관리되는 프런트 도어이며 PWA를 제공합니다. 휴대폰은 /api/*의 HTTPS를 통해 lead에 접근하며 다른 대상과는 통신하지 않습니다. lead는 crew secret을 전송하는 고정된 상호 TLS를 통해 /crew/v1/*에서 각 member에 접근합니다. member는 프런트 도어가 없는 완전한 Collie이며, 자체 에이전트, 저널, 업로드 및 감사 로그를 유지합니다. 관리는 Herdr UI 작업 없이 CLI를 통해서만 전적으로 이루어집니다. 통신 규격 자체는 CREW_PROTOCOL.md에 명시되어 있습니다.

코드는 사용자의 ssh를 통해 모든 머신으로 전달됩니다. crew add은 해당 방식으로 member를 설치하고 crew update은 동기화합니다. crew 링크는 런타임 데이터를 전송하며, 배포 채널로 사용되지 않습니다.

deputy는 lead가 사전에 지정한 하나의 피어입니다. 세 개의 라우트가 있는 대기 도어를 바인딩하며, 해당 도어는 절대 게시되지 않습니다. lead의 무응답이 이를 활성화하고, 사용자 자신의 페어링 자격 증명이 이를 소진하므로, lead가 없는 동안에도 휴대폰이 deputy에 연결할 수 있습니다.

install.sh로 설치하지 않은 구성원

crew는 파일 소유자가 다른 구성원을 제외하고 휴대전화에서 모든 구성원을 업데이트합니다.

collie crew update 및 휴대전화의 탭 한 번 crew 업데이트는 모두 이전 릴리스 옆에 새 릴리스를 배치하고 교체합니다. 이는 설치 스크립트와 Herdr가 생성하는 두 가지 설치 환경에서 작동하며, 모든 설치 환경에서 작동하는 것은 아니므로 crew는 실패 처리하는 대신 다른 환경들을 보고합니다.

패키지로 설치된 구성원은 패키지 관리자의 업데이트를 대기합니다. pacman, nix 또는 brew가 파일을 배치한 경우 해당 패키지 관리자가 소유하므로, Collie는 자신이 소유하지 않은 파일을 대체하지 않습니다(패키지 설치본). crew는 해당 머신에 업데이트를 전송하지 않고, 이름을 지정할 수 있는 경우 해당 접두사의 명령과 함께 "waits for the package manager"로 표시하며, 해당 머신 없이 실행을 완료된 것으로 처리합니다. 해당 머신에서 해당 명령을 실행하면 동기화되며, 다음 확인 시 해당 줄이 지워집니다.

패키지된 LEAD는 여전히 해당 member의 버전을 맞춥니다. lead는 동일한 이유로 자체 이동을 거절하며, 거절 사유의 전부는 다음과 같습니다. 휴대폰과 collie crew update 모두 모든 멤버를 lead가 현재 실행 중인 버전으로 맞추며, 한 번의 확인으로 모두 처리됩니다. 패키지 관리자가 lead를 이동하고 사용자가 lead에서 collie restart를 실행한 후에는 아무것도 자동으로 맞춰지지 않습니다. 휴대폰의 Updates 페이지에서 한 번 더 확인하면 멤버들이 lead의 새 버전으로 업데이트됩니다.

소스 체크아웃은 소스 체크아웃을 가진 lead 아래에서 완전한 멤버가 됩니다. 직접 복제하고 빌드한 멤버는 체크아웃 lead로부터 크루 업데이트를 받습니다. 해당 lead는 자체적으로 수행하는 것과 똑같이 커밋을 푸시하고, 다시 빌드하며, 재시작합니다. 커밋이 없는 lead 아래에서는 collie crew update이 이를 건너뛰고 해당 머신에서 실행할 collie update --to-tag v<version>를 안내합니다.

따라서 혼합된 crew도 일반적인 crew입니다. 탭 한 번으로 lead가 업데이트할 수 있는 모든 구성원을 동기화하고, 업데이트할 수 없는 구성원의 이름을 지정하며, 해당 패키지 관리자를 실행하고 나면 crew가 다시 동기화됩니다.

crew 이름

crew 이름은 표시용 데이터이며 lead에만 표시됩니다. collie crew invite --name "the shed"은(는) crew가 생성될 때 이름을 지정하며, --name 없이 생성된 crew는 "collie crew"라고 부릅니다. 나중에 변경하려면 lead에서 collie crew rename <name>을(를) 실행합니다. 이 동사는 lead 자체의 crew-trust.json에 있는 이름을 덮어쓰고 bridge를 재시작하므로, collie crew status 및 휴대전화의 crew 페이지에 새 이름이 바로 표시됩니다.

멤버에게는 아무것도 전송되지 않습니다. 이름은 등록 요청에 대한 리드의 응답에 포함되어 한 번 전달되며, 멤버는 이를 표시하지 않고 저장합니다. 이름이 바뀐 뒤 합류한 머신은 새 이름을 받고, 크루에 이미 있던 멤버는 아무도 읽지 않는 필드에 기존 문자열을 유지합니다. 이름은 앞뒤 공백이 제거되며, 최대 64자이고 제어 문자를 포함할 수 없습니다. 피어나 크루에 속하지 않은 머신에서 실행하면 동사가 작업을 거부하고 실행해야 할 위치를 안내합니다.

1.7.0 또는 1.8.x에서 1.9.0으로 업데이트

lead를 1.9.0으로 이동하기 전에 모든 member를 1.8.x로 업데이트하십시오. 1.9.0은 한 가지 버전의 crew 링크를 사용하며, 1.8.0은 이를 지원하는 가장 오래된 빌드입니다.

어떤 릴리스인지 기억할 필요는 없습니다. 1.8.0부터는 향후 릴리스에서 crew 링크가 변경될 때 밴드, 업데이트 카드, 일일 푸시의 업데이트 알림을 통해 알려주며, 항상 같은 내용을 안내합니다. 리드를 먼저 업데이트하고 멤버가 그 뒤를 따릅니다.

1.8.0은 머신이 읽는 이름을 변경합니다. 회선 경로, 두 개의 환경 변수 키, 세 개의 상태 파일, 저널 접두사가 이제 모두 crew로 표기됩니다(ADR 0039). 링크는 이전과 완전히 동일하게 작동하며 스크립트로 작성된 항목을 당일 즉시 변경할 필요는 없습니다.

1.8.0은 한 릴리스 동안 1.7.0 member를 지원했지만, 1.9.0은 지원하지 않습니다. 1.8.0 lead는 이전 경로에도 응답했으므로 1.7.0에 머물러 있는 member도 계속 이를 따랐습니다. 1.9.0에서는 해당 기능이 제거되었으며, 이는 ADR 0039에서 예고된 내용입니다.

1.9.0 lead 아래에 여전히 1.7.0 상태인 member는 두 번 표시되며, 둘 다 무시되지 않습니다. lead의 사전 검사에서 version 검사가 빨간색으로 표시되며, 두 버전과 실행할 명령이 함께 나타납니다. 이 빨간색 상태는 완료할 수 없는 롤아웃을 시작하지 않고 crew 업데이트를 차단합니다. collie crew status에서 동일한 member는 "this build speaks 2"로 끝나는 이유와 함께 incompatible 상태로 표시됩니다.

해당 머신에서 직접 member 버전을 업데이트하십시오. 1.9.0 lead는 더 이상 링크를 통해 해당 member에 도달할 수 없으므로, 해당 머신에서 collie update을(를) 실행하여 1.8.x 이상으로 업데이트하면 lead가 다음 폴링 시 이를 감지합니다.

새로운 이름

1.9.0으로 이동하기 전에 자체 .env에서 두 환경 키의 이름을 바꾸십시오. 1.9.0 빌드는 이전 키를 읽지 않으며 경고도 표시하지 않습니다.

업데이트 기간에 걸친 저널에서는 두 접두사를 모두 grep하십시오:

journalctl --user -u collie | grep -E '\[(crew|pack)\]'

업데이트 전에 기록된 줄에는 [pack]이(가) 표시되고, 업데이트 후에 기록된 줄에는 [crew]이(가) 표시됩니다. 전체 crew가 1.8.0으로 전환되면 [crew]만 필터링하십시오.