jamesyc/TimeCapsuleSMB

Apple AirPort Time Capsules는 AFP와 SMB1만을 지원합니다. Apple은 macOS 27에서 AFP 지원을 제거했습니다 (그리고 SMB1 지원은 오래전에 macOS에서 제거되었습니다). 이것은 Time Capsule 자체에서 직접 실행되는 현대적인 Samba 설정입니다. macOS 27은 네트워크 공유로서 Time Capsule에 연결할 수 있으며, 이를 Time Machine 백업용으로 사용할 수 있습니다.

이 프로젝트는 두 부분으로 구성됩니다:

• Apple Time Capsule에서 작동하도록 수정된 Samba 4의 포크 (fork)
• Python 또는 macOS GUI 앱을 통한 Samba 바이너리 설치 프로그램

이제 모든 Time Capsules에서 완벽하게 작동합니다. Time Capsule은 자체적인 Samba 4.24.3 서버를 실행하고, Bonjour를 통해 자신을 알리며 (macOS의 "네트워크" 폴더에 자동으로 나타남), 인증된 SMB3 연결을 수락합니다. 그러면 Finder를 열고 "서버에 연결"을 선택하여 Apple의 레거시 스택에 의존하는 대신 일반적인 SMB URL을 사용할 수 있습니다. 또한 해당 디스크를 Time Machine 백업용으로 사용할 수 있습니다:

Apple의 경험을 그대로 재현할 수 있습니다: 이 소프트웨어를 설치한 후에는 장치의 IP 주소가 변경되더라도 다시 걱정할 필요가 없습니다. 설정 앱의 Time Machine에 자동으로 나타나며, mDNS/Bonjour를 사용하므로 IP 주소가 고정적이지 않고 변경되더라도 문제없이 작동합니다.

"Install" 또는 deploy 스크립트는 Time Capsule의 /mnt/Flash에 파일을 설치하고, 하드 드라이브의 루트에 .samba4 폴더를 생성합니다. uninstall 스크립트는 관리되는 해당 파일들을 제거하며, 선택적으로 이후에 장치를 재부팅할 수 있습니다.

NetBSD 6 장치는 부팅 시 자동으로 시작됩니다. 이전 버전인 NetBSD 4 장치는 재부팅할 때마다 수동으로 활성화(activate)해야 할 수도 있습니다, 또는 재부팅 시 Samba가 자동으로 시작되도록 펌웨어를 플래싱(부트 훅 추가)하는 데 이 도구를 사용할 수 있습니다. 만약 activate를 실행하지 않으면...

재부팅 또는 부트 훅(boot hook) 플래싱 후 명령어를 실행하지 않으면, 구형 Time Capsule에서 Samba가 자동으로 시작되지 않습니다! 현재 인증 모델은 모든 사용자를 사용자 이름(username)으로 허용하며, Samba 비밀번호는 현재 Time Capsule 기기 비밀번호를 사용합니다. 부팅 시 기기는 실시간 AirPort syPW 값을 읽어 RAM에 Samba 비밀번호 파일을 생성하므로, 기기 비밀번호를 변경하더라도 재부팅 후에 반영됩니다. 게스트 액세스(Guest access)는 비활성화되어 있습니다.

AirPort Extreme 기기는 공식적으로 지원되지 않습니다. 비공식적으로는 잘 작동합니다. 이 도구는 하드 드라이브에 설치되므로, 하드 드라이브가 없는 AirPort Extreme에서는 작동하지 않습니다 (플래시 메모리에 바이너리를 저장할 공간이 충분하지 않기 때문입니다).

필요 사항:

• Time Capsule과 동일한 로컬 네트워크에 있는 macOS 14+ 또는 Linux 머신
• Time Capsule 비밀번호

Python 설정을 위해 필요한 사항:

• Python 3.9+
• doctor를 위해 로컬에 설치된 smbclient
• macOS 사용자의 경우 설치된 Homebrew

최초 설정 중 필요한 경우 configure를 통해 Time Capsule의 SSH를 활성화할 수 있습니다.

또한, 숙련자로서 직접 설치(DIY)를 원한다면, NetBSD 6 기기용 /bin/samba4/smbd, NetBSD 4 리틀 엔디언(little-endian) 기기용 /bin/samba4-netbsd4le/smbd, 또는 NetBSD 4 빅 엔디언(big-endian) 기기용 /bin/samba4-netbsd4be/smbd 바이너리를 Time Capsule로 복사하여 직접 설정할 수 있습니다. 바이너리는 정적 컴파일(statically compiled)되어 있으므로 다른 것은 필요하지 않습니다. 작동하는 바이너리는 이 저장소의 bin/ 디렉토리에 저장되어 있으며, 일반적인 사용자 워크플로우는 체크인된 이 파일들을 직접 사용합니다. Samba를 직접 빌드할 필요는 없지만, 만약 직접 smbd를 다시 빌드하고 싶다면 NetBSD 머신에서 build/에 있는 스크립트를 실행하십시오.

• 여기서 앱의 최신 릴리스(release)를 다운로드하십시오: https://github.com/jamesyc/TimeCapsuleSMB/releases

• 앱의 압축을 풀고 실행하십시오. 만약 "열 수 없음" 경고가 나타나면, 이 앱에 대해 Gatekeeper를 수동으로 비활성화해야 합니다.

• 다음 사항을 확인하십시오:
  로컬 네트워크 (Local Network) 권한이 부여되었는지 확인하십시오 (시스템 설정 (System Settings) → 개인정보 보호 및 보안 (Privacy & Security) → 로컬 네트워크 (Local Network) → TimeCapsuleSMB가 허용되어 있는지 확인한 후, 앱을 종료하고 다시 여십시오). 권한을 부여한 후에는 앱을 닫았다가 다시 여십시오. - 왼쪽 사이드바에서 "장치 추가 (Add Device)"를 클릭하고, 사용자의 장치를 선택하십시오.

• 장치 비밀번호를 입력하고 "장치 저장 (Save Device)"을 클릭하십시오.

• 앱이 Time Capsule의 SSH를 활성화할 때까지 기다리십시오.

• 실패할 경우, 앱을 닫고 다시 연 다음, 저장된 장치를 제거하고 다시 시도하십시오.

• 또한, 장치를 재부팅해 보십시오.

• 왼쪽 사이드바에서 추가된 장치를 클릭한 다음, "설치/업데이트 (Install/Update)" 탭을 클릭하십시오.

• "설치/업데이트 (Install/Update)"를 클릭하여 장치에 배포하십시오.

• 장치 배포에 실패하면, 앱에서 저장된 장치를 제거한 다음 위 4단계로 돌아가 "장치 추가 (Add Device)"를 다시 시도하십시오. 모든 파일을 복사하는 데 한 번 이상의 배포가 필요할 때가 있습니다.

• 배포 중에 장치가 재설정될 수 있다는 보고가 있습니다. 자세한 내용은 이 이슈(issue)를 참조하십시오.

• (1~4세대 장치 전용) 유지 관리(maintenance) 페이지의 "Persistent NetBSD4 Boot Hook" 섹션으로 이동하십시오. 재부팅 후 장치가 Samba를 자동으로 시작할 수 있도록 펌웨어 패치(firmware patch)를 설치하십시오. "백업 및 검사 (Back Up and Inspect)" 및 "패치 계획 (Plan Patch)"을 클릭하여 설치 가능 여부를 확인한 다음, "패치 쓰기 (Write Patch)"를 실행하여 장치에 플래싱(flash)하십시오.

• (선택 사항) Samba가 완전히 시작될 때까지 5~10분 동안 기다린 다음, 점검 (Checkup) 탭으로 이동하여 점검 (Checkup)을 실행하십시오.

더 자세한 정보는 FAQ를 읽어보시기 바랍니다. FAQ를 통해 해결할 수 없는 문제가 발생하면, 이곳에 이슈(issue)를 등록하여 도움을 요청해 주시면 감사하겠습니다.

이 저장소(repository)를 Mac 또는 Linux 머신의 폴더로 다운로드(또는 git clone 실행)하십시오.

이 저장소의 루트(root)에서 실행할 수 있는 일반적인 빠른 시작(quick start) 명령은 다음과 같습니다:

./tcapsule bootstrap

.venv/bin/tcapsule configure

설정/환경 설정 (config/settings) 파일을 저장합니다. .venv/bin/tcapsule deploy

설정 파일에 따라 Time Capsule에 배포 (deploy) 합니다. .venv/bin/tcapsule doctor

모든 것이 제대로 작동하는지 확인합니다. .venv/bin/tcapsule flash

플래시 메모리 (flash memory)를 백업합니다. 그리고 .venv/bin/tcapsule flash --patch

패치 (patch) 합니다.

문제가 발생할 경우:

.venv/bin/tcapsule activate

NetBSD 4 장치에서 재부팅 후 Samba가 자동으로 시작되지 않을 때 실행합니다. .venv/bin/tcapsule fsck

배포 (deploy) 전 내부 디스크 수리가 필요한 경우 실행합니다. .venv/bin/tcapsule discover

모든 mDNS/Bonjour 장치 목록을 나열합니다. .venv/bin/tcapsule repair-xattrs

잘못된 확장 속성 (xattrs)으로 인해 디스크의 손상된 파일을 수리합니다. .venv/bin/tcapsule uninstall

나중에 TimeCapsuleSMB를 제거하고 싶은 경우 실행합니다.

Time Capsule 설정을 마친 후 Mac에서 제거하고 싶다면 이 TimeCapsuleSMB 폴더를 그냥 삭제하면 됩니다. 모든 스크립트/바이너리(binaries) 등은 TimeCapsuleSMB 폴더에 저장되어 있습니다 (따라서 Mac을 정리하고 싶다면 폴더를 삭제하는 것만으로 충분합니다).

버그를 발견하신다면, 도움을 위해 이곳에 이슈 (issue)를 등록해 주시면 감사하겠습니다.

실행:

./tcapsule bootstrap

이 명령은 이 폴더 내의 로컬 Python 환경을 준비합니다. .venv 폴더를 생성하고, 발견 (discovery), 배포 (deployment), 검증 (verification)에 필요한 Python 의존성 (dependencies)을 설치하며, 로컬 tcapsule 명령을 해당 가상 환경 (virtualenv)에 설정합니다.

smbclient 또는 sshpass가 없는 경우, bootstrap은 macOS 14 이상에서는 Homebrew를 통해, Linux에서는 감지된 패키지 관리자 (package manager)를 통해 이를 설치하려고 시도합니다. 이전 버전의 macOS에서는 smbclient와 sshpass가 이미 수동으로 설치되어 있어야만 계속 진행할 수 있습니다. NetBSD 4 장치는 펌웨어에서 사용 가능한 원격 scp를 제공하지 않기 때문에 sshpass가 필요합니다.

이 저장소 (repo)를 처음 사용하는 경우, 이것이 저장소 로컬 런처 (repo-local launcher)로 실행해야 하는 유일한 명령입니다. 이 단계 이후에는 .venv/bin/tcapsule ...을 사용하여 명령을 실행하십시오.

계속하기 전에 로컬 저장소 전용 설치 상태를 검사할 수 있습니다:

.venv/bin/tcapsule paths
.venv/bin/tcapsule validate-install

실행:

.venv/bin/tcapsule configure

이 명령은 저장소(repo) 폴더에 숨겨진 .env 파일을 생성하며, 다른 tcapsule 명령들은 해당 파일을 로컬 장치 설정(local device configuration)으로 사용합니다.

configure가 시작될 때, 도구는 먼저 mDNS/Bonjour를 통해 로컬 네트워크에서 사용자의 Time Capsule을 검색하려고 시도합니다. 장치를 찾으면 SSH 대상(SSH target)을 자동으로 채워줍니다. 찾지 못할 경우, 일반적인 수동 프롬프트 흐름(manual prompt flow)으로 넘어갑니다.

configure는 SSH 접속 가능 여부도 확인합니다. 만약 SSH가 닫혀 있다면, 내장된 Python 3 ACP 클라이언트를 사용하여 SSH를 활성화하고, 장치를 재부팅한 뒤, SSH가 올라올 때까지 기다렸다가 정상적인 탐색 흐름을 계속합니다. 만약 비밀번호가 틀리면, 잘못된 .env 파일을 작성하는 대신 다시 물어봅니다.

여기서 입력한 비밀번호는 TC_PASSWORD로 로컬에 저장되어 도구가 SSH와 ACP를 계속 사용할 수 있게 합니다. 관리되는 Samba 런타임(managed Samba runtime)은 부팅 시 Time Capsule의 현재 장치 비밀번호를 읽습니다. 즉, 설정 후에는 일반적으로 다음과 같이 연결합니다:

• 사용자 이름(username): admin (또는 다른 사용자 이름)
• 비밀번호(password): 설정 과정에서 입력한 것과 동일한 Time Capsule 비밀번호

Samba는 Apple의 내부 비밀번호 백엔드(password backend)를 직접 사용하지 않습니다. 부팅 스크립트는 AirPort의 syPW 설정을 읽고, mdns-advertiser에게 NT 해시(NT hash) 생성을 요청하며, smbd가 시작되기 전에 RAM 전용 Samba 인증 파일들을 작성합니다.

실행:

.venv/bin/tcapsule deploy

이 단계는 장치에 Samba를 설치(또는 업데이트)합니다. 체크인된 바이너리(binaries)를 검증하고 페이로드(payload)와 부트 파일(boot files)을 Time Capsule로 복사합니다. Samba 비밀번호 파일은 관리되는 런타임이 스테이징(stages)될 때마다 장치의 RAM에 생성됩니다. 새 버전을 업데이트하려면 deploy를 실행하면 됩니다.

Gen 5 NetBSD 6 장치의 경우, deploy는 새 런타임이 깔끔하게 올라올 수 있도록 장치를 재부팅합니다.
이전 세대인 Gen 1-4 NetBSD 4 장치의 경우, deploy는 RAM 디스크를 비우기 위해 재부팅을 수행하고, SSH가 복구될 때까지 기다린 다음 /mnt/Flash/rc.local을 실행합니다.

. 구형 장치들은 deploy 과정의 일부가 아닌 이후의 재부팅 시 여전히 tcapsule activate가 필요합니다.

. 기본적으로 tcapsule deploy는

배포 후 재부팅을 수행하고 장치가 다시 돌아올 때까지 기다립니다. 재부팅 확인 프롬프트를 건너뛰고 싶다면 다음과 같이 실행할 수 있습니다:

.venv/bin/tcapsule deploy --yes

또한 --no-nbns, --no-reboot, --dry-run과 같은 다른 플래그들도 존재하지만, 특별한 이유가 없다면 그대로 두십시오. --no-reboot는

파일을 업로드하고, 매니저 프로세스(manager process)와 wcifsfs를 중지한 다음, /mnt/Flash/rc.local을 실행하여 배포된 런타임(runtime)을 즉시 시작합니다.