PandaVPN CLI FAQ

Panda CLI는 Panda의 명령줄 클라이언트이며 터미널을 통해 다음 작업을 지원합니다.

• 로그인 및 계정 관리
• 노드 새로고침 및 노드 연결
• PandaVPN / Proxy / WireGuard / Auto 모드 전환
• 시스템 프록시 구성
• Split rules 분할 규칙
• Split DNS 구성
• Kill-switch 보호
• Auto-connect
• 로그 및 진단

내부 테스트 사용자, 개발자, 고급 사용자 및 스크립트 기반 작업이 필요한 테스트 시나리오에 적합합니다.

Panda CLI는 명령줄을 통해 작동하므로 다음에 더 적합합니다.

• 자동화 테스트
• 원격 문제 해결
• 스크립트 기반 연결
• 상세 진단 정보 확인
• Kill-switch, DNS, 라우팅, 시스템 프록시 등 저수준 동작 검증

데스크톱 클라이언트는 일반 사용자의 일상적인 그래픽 작업에 더 적합합니다.

참고: 기존 Qt 데스크톱 클라이언트와 CLI가 VPN / 시스템 프록시를 동시에 관리하는 것은 권장되지 않습니다. 서로의 구성을 덮어쓰는 것을 방지하기 위해서입니다.

일부 기능에는 다음과 같은 시스템 수준 권한이 필요합니다.

• TUN / WireGuard 네트워크 인터페이스 생성
• DNS 수정
• 시스템 프록시 설정
• Kill-switch 적용
• 라우트 복구
• packet VPN runtime 관리

따라서 CLI는 플랫폼에 맞는 daemon / service를 통해 이러한 작업을 수행합니다.

플랫폼별 daemon 형태:

핵심 차이는 다음과 같습니다. Windows와 macOS에서는 일반적으로 설치 패키지를 통해 service가 자동으로 설치되지만, Linux에서는 일반적으로 사용자가 sudo panda service install을 수동으로 실행해야 합니다.

Windows에서는 설치 패키지를 사용하지 않고 바이너리를 수동으로 배치하는 경우에만 관리자 PowerShell에서 다음을 실행해야 합니다.

panda service install windows

macOS에서는 개발 및 디버깅 중이거나, .pkg 설치 패키지를 사용하지 않았거나, daemon이 자동으로 시작되지 않을 때만 다음이 필요합니다.

sudo panda start

Linux에서는 다음을 권장합니다.

sudo panda service install
panda service status

네, 동일합니다. 차이는 주로 다운로드하는 설치 패키지의 아키텍처입니다.

설치 단계, 명령어, 서비스 관리 방식은 동일합니다. 설치 패키지가 자동으로 권한을 상승시키고 Windows Service를 등록합니다.

주로 다음을 지원합니다.

자주 쓰는 설정:

panda mode auto
panda mode pandavpn global
panda mode proxy global
panda mode wireguard

현재 openvpn은 사용자 문서에서 주요 모드로 표시하는 것을 권장하지 않습니다.

권장 사항:

주의: mode proxy와 Kill-switch는 동시에 사용할 수 없습니다.

mode auto는 새 버전의 기본 모드입니다.

동작 방식은 다음과 같습니다.

• API node / smart connect가 meta.protocol에 따라 runtime을 우선 선택합니다.
• WireGuard가 추천되면 WireGuard를 먼저 시도합니다.
• WireGuard metadata, 주소 할당, runtime 시작, handshake 또는 연결성 탐지가 실패하면 SS payload에서 컴파일된 PandaVPN global로 폴백합니다.
• SS, OPENVPN, 알 수 없거나 누락된 프로토콜은 PandaVPN global을 fallback으로 사용합니다.
• mode auto는 policy 파라미터를 받지 않으며, 해석된 runtime은 항상 global입니다.

신규 사용자에게 권장:

panda mode auto
panda connect

direct-region이 권장 표기입니다. bypass-region / bypass는 호환 alias입니다.

예:

panda mode pandavpn direct-region in

호환 alias와 동일합니다:

panda mode pandavpn bypass-region in

새 버전은 더 완전한 split profile 작성 방식을 지원합니다.

panda mode pandavpn split default direct proxy-region <cc>
panda mode pandavpn split default proxy direct-region <cc>

자주 쓰는 token:

예시:

panda mode pandavpn split default direct proxy-region us custom-rules
panda mode pandavpn split default proxy direct-region in direct-lan custom-rules

초보자 문서에는 긴 명령을 표시하지 않는 것이 좋으며, 고급 split 문서에 넣는 것이 적합합니다.

doctor는 현재 Panda CLI의 주요 상태를 확인하는 읽기 전용 진단 명령입니다.

panda doctor
panda doctor --json

짧은 명령:

panda do

중점적으로 확인할 항목:

runtime
kill_switch
selected_node
vpn_dns
dns_lockdown
split_policy
system_proxy_state
vpn_routes
last_error

trace는 특정 대상이 어떤 규칙, DNS action, route를 사용하는지 확인하는 데 사용합니다.

panda trace example.com:443
panda trace 8.8.8.8:53 --json

주의: 전체 trace 기능에는 active PandaVPN packet runtime이 필요합니다. 호환되는 runtime이 없으면 제한적인 검증만 가능하거나 legacy trace로 fallback됩니다.

보통 공식 service / LaunchDaemon이 설치되어 있는데, 추가로 수동 실행을 했기 때문에 발생합니다.

sudo panda start

sudo panda start는 unmanaged / 관리되지 않는 daemon을 시작하며, 이 daemon이 공식 daemon과 동시에 다음 항목을 관리할 수 있습니다.

• VPN route
• DNS
• TUN
• system proxy
• Kill-switch

처리 원칙은 daemon을 하나만 유지하는 것입니다.

macOS / Linux에서 일반적으로 사용하는 처리:

panda disconnect
panda kill-switch off
sudo panda stop
panda repair
panda doctor

Linux에서 systemd service를 사용하는 경우, 이후 공식 서비스를 다시 시작합니다.

sudo panda service restart
panda doctor

macOS에서 .pkg 설치를 사용하는 경우 보통 LaunchDaemon / helper가 daemon을 관리하도록 두고, sudo panda start를 장기적인 일상 시작 방식으로 사용하지 마세요.

VPN 연결만 끊으려면 daemon을 종료할 필요가 없습니다:

panda disconnect
panda kill-switch off

정말 daemon을 중지하려면:

sudo panda stop

확인:

panda status

panda daemon unavailable가 표시되면 main daemon이 중지되었다는 뜻입니다.

참고: macOS .pkg로 설치된 LaunchDaemon / helper는 시스템에서 관리될 수 있습니다. 일반 사용자가 서비스를 자주 수동으로 중지하는 것은 권장하지 않습니다.

panda log
panda log --lines 200
panda log --all

Logs 정리:

panda log clear

Debug 임시 활성화:

panda log level debug dns,tcp --ttl 10m

기본값 복원:

panda log level reset

panda repair는 더 포괄적이며 다음을 복구할 수 있습니다:

• VPN route
• DNS snapshot
• Kill-switch guard
• system proxy 관련 상태

panda proxy repair는 주로 현재 사용자의 system proxy drift를 복구합니다.

panda repair
panda proxy repair

Fresh install에서는 기본값이 proxy system-proxy on입니다.
사용자가 명시적으로 off를 저장한 적이 있으면 해당 구성이 유지됩니다.

확인 또는 설정:

panda proxy system-proxy on
panda proxy system-proxy off
panda proxy system-proxy lock-on

주의: mode auto, pandavpn, wireguard에서는 VPN runtime이 저장된 system proxy 선호 설정을 무시합니다. VPN companion proxy는 계속 사용할 수 있으며 scoped egress를 사용합니다.

Windows system proxy는 현재 사용자의 HKCU WinINET 설정이며 per-user user-agent가 필요합니다.
SSH 또는 비대화형 세션에서는 proxy repair가 user-agent를 항상 자동으로 시작하지 못할 수 있습니다.

권장:

panda proxy status
panda proxy repair
panda doctor

그래도 적용되지 않으면 데스크톱 로그인 세션에서 다시 시도하세요.

Linux Phase 1은 주로 GNOME gsettings를 지원합니다.
KDE / XFCE 같은 환경은 unsupported로 표시될 수 있습니다.

이것이 반드시 PandaVPN packet runtime에 영향을 주는 것은 아니지만, system proxy mode 경험에는 영향을 줄 수 있습니다.

Kill-switch의 의미는 TUN을 통한 트래픽만 허용하고, 다른 일반 트래픽은 차단하는 것입니다.

proxy mode는 standalone 로컬 프록시 모드이며, packet VPN / TUN이 없고 DNS 및 라우팅에 대한 동등한 보호도 제공하지 않습니다. 따라서 Kill-switch는 standalone proxy mode를 지원하지 않습니다.

Kill-switch가 필요할 때는 다음을 사용하세요.

panda mode auto
panda kill-switch on

또는:

panda mode pandavpn global
panda kill-switch on

또는:

panda mode wireguard
panda kill-switch on

아닙니다.

Auto-connect는 주로 daemon / service 시작 시의 best-effort connect와, 시작 시 네트워크가 일시적으로 없을 때의 pending retry를 처리합니다.

켜기:

panda config auto-connect on

끄기:

panda config auto-connect off

이는 일반적인 runtime 자동 재연결 메커니즘이 아닙니다.

Split rules는 특정 도메인, 키워드, regex 또는 IP가 proxy, direct 또는 block으로 처리되도록 지정하는 데 사용됩니다.

Rules 파일:

split/rules/proxy.txt
split/rules/direct.txt
split/rules/block.txt

자주 쓰는 명령:

panda split rules list
panda split rules add proxy suffix:github.com
panda split rules add direct ip-cidr:10.0.0.0/8
panda split rules add block keyword:adservice

현재 알려진 제한 사항: login 후 retry를 기다리는 pending auto-connect는 자동으로 wake되지 않습니다.

login 후 수동으로 실행하는 것을 권장합니다.

panda connect

일반적으로 필요하지 않습니다. Split DNS configuration 변경 사항은 hot-load됩니다.

자주 쓰는 명령:

panda split dns status
panda split dns local set 223.5.5.5 114.114.114.114
panda split dns policy tunnel-only
panda split dns fake-ip on

플랫폼이 일부 local DNS source를 지원하지 않으면 doctor가 warning을 표시합니다.