iOS 네트워크 확장
iOS 네트워크 제어에 필요한 네트워크 확장을 에이전트 맥에 설치하고 확장이 멈췄을 때 복구합니다.
iOS: 네트워크 확장이 설치되지 않았습니다
iOS 시뮬레이터에서 네트워크 제어를 하려면 에이전트 맥에 tapflow 네트워크 확장이 설치돼 있어야 합니다. 확장은 tapflow와 함께 오므로 따로 내려받지 않습니다. 아래 명령이 패키지에 들어 있는 확장을 설치합니다.
1. 설치
처음 설정하는 맥이라면 iOS 셋업이 확장까지 함께 처리합니다.
tapflow setup ios이미 tapflow를 쓰던 맥이라면 셋업을 다시 돌리지 않으므로 별도 명령을 씁니다. 확장이 없던 시절에 설정한 맥이 여기 해당합니다.
tapflow migrate net-filter2. 승인
설치를 요청하면 macOS 승인 창이 뜹니다. 시스템 설정 열기를 누르세요. 파랗게 강조된 확인은 창만 닫고 승인은 하지 않습니다.
시스템 설정 → 일반 → 로그인 항목 및 확장 프로그램 → 네트워크 확장에서 tapflow 항목을 켭니다. (관리자 암호가 필요합니다.)
승인은 맥 앞에서만 할 수 있습니다. 브라우저에서 누를 수 있는 대체 경로는 macOS가 제공하지 않습니다.
승인 화면은 명령이 열어줄 수 있습니다. 이 맥에 승인된 tapflow 확장이 없으면 명령은 설치를 시작하기 전에 승인 화면을 열어줄지 묻습니다. 동의하면 macOS가 승인을 기다리기 시작하는 즉시 화면이 열립니다. 거기서 TapflowNetFilter를 켜면 설치가 그대로 끝납니다. 이미 승인을 기다리는 확장이 있으면 macOS는 승인 창을 다시 띄우지 않습니다. 그래서 명령을 다시 실행할 때는 이 화면이 가장 빠른 길입니다.
입력과 출력이 모두 터미널에 연결돼 있을 때만 묻습니다. 파이프나 리디렉션을 쓰면 터미널에서 실행해도 묻지 않습니다.
처음 2분을 넘겨도 끝이 아닙니다. 설치는 승인을 2분까지 기다립니다. 그 안에 켜지 못했더라도 명령이 물을 수 있는 환경이고 제안을 거절하지 않았다면 명령이 최대 2분 더 기다립니다. 그 사이에 켜면 명령이 필터를 켭니다. 이미 승인된 확장을 교체할 때처럼 macOS가 묻지 않을 것으로 보여 미리 묻지 않았다면 이때 화면을 열지 묻습니다.
필터를 켜는 순간 맥에 이미 열려 있던 연결이 잠깐 끊길 수 있습니다. SSH 세션도 마찬가지이므로 SSH로 접속해 있다면 맥 앞에서 실행하세요. 켤 때 macOS가 네트워크 콘텐츠 필터링을 허용할지 물으면 허용하세요.
화면이 뜨지 않으면 위 경로로 직접 가세요. 명령은 창이 열렸는지 알 수 없어서 경로를 함께 보여줍니다.
제안을 거절했거나 묻지 않는 환경에서 실행했다면 처음 2분 안에 직접 승인하지 않는 한 명령은 승인 대기 상태로 끝납니다. 거절한 제안은 다시 묻지 않습니다. 더 기다린 2분 안에 켜지 못한 경우도 승인 대기로 끝납니다. 승인한 뒤 같은 명령을 한 번 더 실행하세요. 다시 실행하면 필터가 켜집니다.
더 기다리는 2분 동안 시뮬레이터를 켜는 등 기기를 쓰기 시작했다면 필터를 켜지 않고 멈춥니다. 명령이 찾은 것을 알려주므로 그것을 끄고 다시 실행하세요. 처음 2분 안에 승인하면 확장이 스스로 필터를 켭니다. 그래서 기기 확인은 설치를 시작할 때 한 번뿐입니다.
3. 재시작이 필요한 경우
이미 설치된 확장을 교체하면 맥을 재시작해야 완료됩니다. 재시작 전까지는 이전 버전이 계속 동작합니다. 파일은 새 것인데 macOS가 실행 중인 것은 옛 것인 상태라, 대시보드는 여전히 준비되지 않았다고 말합니다.
무엇이 설치돼 있는지 확인
tapflow doctor ios네 가지를 따로 말합니다. 설치돼 있는가, 승인됐는가, 켜져 있는가, 그리고 이 맥의 버전들이 이 tapflow가 싣고 온 것과 같은가. 뒤의 두 항목이 따로 있는 이유는 앞의 것들이 다 맞는데도 동작하지 않는 상태가 있기 때문입니다 — 교체 직후 재시작 전이 하나입니다. 필터가 꺼져 있는 경우가 다른 하나입니다. 꺼져 있는 상태는 자기 버전이 없습니다. 확장은 활성으로 남으므로 버전은 전부 맞게 읽히는데 아무것도 필터링되지 않습니다.
버전을 가진 것은 둘입니다. /Applications의 앱과 그 안의 시스템 확장입니다. 둘은 따로 움직입니다. 앱만 바뀐 릴리즈가 돌아가는 필터를 교체할 이유는 없기 때문입니다. 검사는 뒤처진 쪽을 지목하고, 각각 할 일이 다릅니다.
| 무엇이 뒤처졌다고 하나 | 할 일 |
|---|---|
/Applications의 앱 | tapflow migrate net-filter. 앱만 복사되고 macOS는 활성화를 건너뛰므로 아무것도 끊기지 않습니다. 에이전트가 그 바이너리를 실행하므로 낡은 앱은 문제가 됩니다 |
| 확장, 재시작 안내와 함께 | 맥을 재시작하세요. 교체본은 이미 설치돼 있고 그때 끝납니다 |
| 확장, 재시작 안내 없이 | tapflow migrate net-filter |
| 이 맥이 더 새 tapflow용이다 | 대신 이 체크아웃을 최신으로 올리세요. 그 방향은 migrate가 거부합니다. 새 필터를 덮어쓰면 그것에 기대는 에이전트가 망가지기 때문입니다 |
앱은 지워졌는데 확장이 아직 돌고 있으면 tapflow는 재설치를 거부합니다. 확장 버전은 어떤 필터가 도는지를 말할 뿐 그 앱이 무엇이었는지는 말하지 않습니다. 그래서 그 맥이 여기보다 새 tapflow로 설정됐는지 알 방법이 없습니다. 덮어쓰면 누군가 기대고 있을지 모를 동작 중인 필터를 교체하게 됩니다. 버전이 맞는 tapflow에서 재설치하거나, 확장을 정리하고 새로 시작하세요. 정리하는 순서는 tapflow doctor ios와 설치를 거부한 명령이 함께 출력합니다.
- 필터를 끕니다. 앱이 없으므로 패키지에 들어 있는 바이너리로 끕니다. 명령이 그 경로를 그대로 적어 줍니다.
- 시스템 설정 → 일반 → 로그인 항목 및 확장 프로그램 → 네트워크 확장에서 TapflowNetFilter 옆 ⋯ 버튼을 눌러 확장 프로그램 삭제를 고릅니다.
/Applications에 앱이 없어도 삭제됩니다. - 맥을 재시동합니다. 제거는 이때 끝납니다.
systemextensionsctl uninstall은 시스템 무결성 보호(SIP)가 켜진 맥에서 거부되므로 쓸 수 없습니다.
그래도 안 될 때
설치는 실패 종류마다 다른 코드로 끝납니다.
| 코드 | 뜻 |
|---|---|
| 1 | 활성화 실패 |
| 2 | 설정을 읽지 못함 |
| 3 | 설정을 저장하지 못함 |
| 4 | 120초 안에 승인되지 않음. 입력과 출력이 모두 터미널이면 명령이 이어서 기다리고 아직 묻지 않았다면 승인 화면을 열지 먼저 묻습니다. 거기서도 켜지지 않았거나 물을 수 없는 환경이었거나 제안을 거절했다면 명령은 승인 대기로 끝나므로 시스템 설정에서 승인하고 다시 실행하세요 |
| 5 | 맥을 재시작해야 완료됩니다 |
| 6 | 시스템 확장 관리자가 45초 안에 응답하지 않음 |
| 7 | 실행 중인 필터에게서 답을 받지 못함 |
| 8 | 이 빌드가 이해하지 못하는 인자. 설치된 필터 앱이 에이전트보다 오래된 버전일 때 나올 수 있습니다 |
확장이 무엇을 보고 무엇을 보지 않는지는 네트워크 제어에 있습니다.
문제 해결
iOS: 필터를 교체하는 중에 맥의 네트워크가 끊겼습니다
이 필터는 시뮬레이터 것만이 아니라 맥이 새로 맺는 모든 연결을 판정합니다. 필터가 켜져 있는 상태에서 멈추면 macOS는 검사받지 않은 트래픽을 흘려보내는 대신 전부 막습니다. 필터로서는 안전한 선택이고 쓰는 입장에서는 갑작스러운 일입니다. 확장을 교체하는 동안 필터가 잠깐 멈춥니다. 그래서 교체할 때 이 일이 생깁니다.
증상은 느려짐이 아니라 즉시 실패입니다. 오래 기다리는 것이 아니라 **No route to host**가 바로 뜹니다. 이미 열려 있던 연결은 그대로 동작하므로 브라우저는 멈췄는데 다른 것은 멀쩡해 보이는 상태가 됩니다.
tapflow migrate net-filter는 진행하면서 필터를 두 번 끕니다. 새 앱을 복사하기 전에 한 번, 활성화하기 전에 한 번입니다. 두 번째는 관문이라서, 끄지 못한 필터 위에 활성화를 하는 대신 명령이 멈추고 알려줍니다. 첫 번째는 최선 노력이라 그것이 듣지 않은 맥에서는 이 절이 설명하는 좁은 창이 그대로 남습니다.
명령이 멈춘 경우에는 필터가 꺼진 채로 남았는지를 알려줍니다. 그 상태에서 네트워크는 정상이고 iOS 네트워크 제어만 빠져 있습니다.
네트워크를 되살리는 데 재시작은 필요 없습니다.
/Applications/TapflowNetFilter.app/Contents/MacOS/TapflowNetFilter --off필터를 경로에서 빼면 트래픽이 돌아옵니다. 필터를 다시 켤 때까지 iOS 네트워크 제어는 쓸 수 없습니다. 마이그레이션을 다시 돌리면 켜집니다.
tapflow migrate net-filteriOS: 오프라인이던 기기가 스스로 온라인으로 돌아왔습니다
오프라인으로 두고 확인하던 중에 기기가 다시 온라인이 됐다는 알림이 뜨면, 그때까지 확인한 오프라인 동작은 다시 확인해야 합니다. 알림이 뜬 시점과 실제로 트래픽이 통과하기 시작한 시점 사이에 요청이 성공했을 수 있기 때문입니다.
에이전트 맥에서 트래픽을 막던 필터가 멈췄습니다. 확장이 시스템 설정에서 꺼졌거나, 죽은 필터 프로세스를 macOS가 다시 띄우는 중입니다. 다시 뜨는 데는 보통 6초 남짓 걸리며 그동안에는 아무것도 막히지 않습니다.
확인
systemextensionsctl listdev.tapflow.netfilter.ext가 [activated enabled]가 아니면 설치·승인 절차로 돌아가세요.
켜져 있는데도 같은 일이 반복된다면 필터 프로세스가 계속 죽고 있습니다.
log show --last 10m --predicate 'subsystem == "dev.tapflow.netfilter"' --info --debug --style compact대처
기기를 다시 오프라인으로 두고 확인을 처음부터 다시 하세요. 필터가 돌아왔다면 버튼은 정상으로 그려집니다. 계속 같은 알림이 뜨면 그 맥에서는 오프라인 확인을 신뢰할 수 없으므로, 원인을 잡기 전까지는 다른 에이전트 맥을 쓰는 편이 낫습니다.
로그는 /tmp/tapflow-netfilter-host.log에 있습니다.
기능 자체는 네트워크 제어를 참고하세요.