mudfish-exclude 사용자 안내서
이 프로그램은 미꾸라지 Cloud VPN 6.5.4 혹은 그 이상 버전에서만 이용 가능합니다.
mudfish-exclude는 Linux용 미 꾸라지에서 특정 프로그램만 미꾸라지 경로에서 제외하여 실행하는 명령줄 도구입니다. 특히 Full VPN 모드를 사용하면서 브라우저, 메신저, 동영상 플레이어, 다운로드 도구 등의 트래픽은 기존 인터넷 회선으로 직접 보내고 싶을 때 사용할 수 있습니다.
일반 프로그램 -> 미꾸라지 경로 -> 중계 서버
mudfish-exclude 앱 -> 기존 기본 경로 -> 인터넷
이 도구는 미꾸라지 대시보드에 설정을 추가하지 않습니다. 제외할 프로그램을 평소 실행 명령 대신 mudfish-exclude로 시작하면 됩니다.
지원 범위: 현재 Linux와 IPv4만 지원합니다. Windows, macOS, Android에서는 사용할 수 없으며 IPv6 트래픽에는 별도의 우회 정책을 적용하지 않습니다.
필요한 환경
다음 조건이 모두 필요합니다.
- Linux용 미꾸라지가 설치되어 있어야 합니다.
- cgroup v2가
/sys/fs/cgroup에 마운트되어 있어야 합니다. ip와iptables명령 및 iptables의 cgroup match 기능을 사용할 수 있어야 합니다.- 정책 라우팅과 방화벽 규칙을 설정할 수 있도록
sudo권한이 있어야 합니다. - Linux의 main 라우팅 테이블에 정상적인 IPv4 기본 경로가 있어야 합니다.
설치된 실행 파일은 보통 다음 위치에 있습니다.
/opt/mudfish/<미꾸라지 버전>/bin/mudfish-exclude
현재 설치 경로는 다음 명령으로 찾을 수 있습니다.
ls /opt/mudfish/*/bin/mudfish-exclude
실행 파일이 PATH에 등록되어 있지 않으면 아래 예제의 mudfish-exclude를 위에서 확인한 전체 경로로 바꾸십시오. 예를 들어 6.5.4 버전의 기본 설치 경로는 /opt/mudfish/6.5.4/bin/mudfish-exclude입니다.
기본 사용법
- 미꾸라지를 실행하고 원하는 아이템 또는 Full VPN 모드를 정상적으로 연결합니다.
- 제외할 프로그램이 이미 실행 중이면 트레이나 백그라운드 프로세스까지 완전히 종료합니다.
- 터미널에서 다음 형식으로 프로그램을 다시 실행합니다.
sudo mudfish-exclude <프로그램> [프로그램 옵션...]
예를 들어 Discord를 미꾸라지에서 제외하려면 다음과 같이 실행합니다.
sudo mudfish-exclude discord
Firefox를 제외하면서 사생활 보호 창을 열려면 다음과 같이 실행합니다.
sudo mudfish-exclude firefox --private-window
실행 파일 경로에 공백이 있다면 따옴표로 묶습니다.
sudo mudfish-exclude "/path/to/My Program" --option
sudo는 네트워크 정책을 설정하는 데 사용됩니다. sudo mudfish-exclude ...로 실행한 프로그램 자체는 가능한 경우 sudo를 호출한 원래 사용자의 UID, GID, 홈 디렉터리와 데스크톱 세션 환경으로 실행됩니다.
알아둘 점
- 제외 정책은
mudfish-exclude로 새로 시작한 프로세스와 그 자식 프로세스에 적용됩니다. - 이미 실행 중인 프로그램에 정책을 나중에 붙일 수는 없습니다. 단일 인스턴스 프로그램이 기존 프로세스를 재사용하지 않도록 먼저 완전히 종료해야 합니다.
- 일반적인 한 번 실행 방식에서는 프로그램과 자식 프로세스가 모두 종료될 때 정책이 자동으로 정리됩니다.
- 여러
mudfish-exclude명령을 동시에 실행할 수 있습니다. 공통 정책은 마지막 제외 프로그램이 종료된 뒤 정리됩니다. - 제외된 프로그램의 IPv4 트래픽은 미꾸라지 중계 서버, 가속 기능 및 해당 경로의 공인 IP를 사용하지 않습니다.
정상 동작 확인
Full VPN 연결 전 의 공인 IPv4 주소와 Full VPN 중계 서버의 공인 IPv4 주소가 서로 다를 때 가장 쉽게 확인할 수 있습니다.
먼저 Full VPN이 연결된 일반 터미널에서 주소를 확인합니다.
curl -4 https://myip.mudfish.net
같은 명령을 mudfish-exclude로 실행합니다.
sudo mudfish-exclude curl -4 https://myip.mudfish.net
첫 번째 결과는 미꾸라지 중계 서버 측 주소, 두 번째 결과는 기존 인터넷 회선의 주소로 표시되어야 합니다. -4는 이 도구의 지원 범위에 맞게 IPv4로만 검사하기 위한 옵션입니다.
브라우저로 확인할 때는 브라우저를 완전히 종료한 뒤 다음처럼 실행하고 https://myip.mudfish.net에 접속하십시오.
sudo mudfish-exclude firefox
종료와 정책 정리
정상 종료 시 별도의 정리 명령은 필요하지 않습니다. 다만 mudfish-exclude 프로세스를 강제 종료했거나, 터미널이 비정상적으로 닫혔거나, 시스템이 중단된 경우에는 정책이 남을 수 있습니다.
먼저 이 도구로 실행한 프로그램을 모두 종료한 뒤 다음 명령을 실행하십시오.
sudo mudfish-exclude --cleanup
실행 중인 제외 프로그램이 있을 때
--cleanup을 사용하면 해당 프로그램의 우회가 즉시 중단될 수 있습니다.
명령 옵션
사용법: mudfish-exclude [옵션] 프로그램 [프로그램 옵션...]
| 옵션 | 설명 |
|---|---|
-h, --help | 도움말을 출력합니다. |
--setup | 제외용 네트워크 정책만 설정하고 종료합니다. 프로그램을 함께 지정할 수 없습니다. |
--cleanup | 제외용 네트워크 정책을 제거하고 종료합니다. 프로그램을 함께 지정할 수 없습니다. |
--no-setup | 기존 정책을 다시 설정하지 않고 지정한 cgroup에 들어가 프로그램을 실행합니다. |
--cgroup NAME | 사용할 cgroup v2 이름을 지정합니다. 기본값은 mudfish-exclude입니다. |
--mark VALUE | 패킷에 사용할 방화벽 mark를 지정합니다. 기본값은 0x6d660001입니다. |
--priority VALUE | IPv4 policy rule 우선순위를 지정합니다. 기본값은 8252입니다. |
--table VALUE | 기존 기본 경로를 담을 라우팅 테이블 번호를 지정합니다. 기본값은 8252입니다. |
옵션 해석을 명확히 끝내려면 -- 뒤에 프로그램을 적을 수 있습니다.
sudo mudfish-exclude -- firefox --private-window
여러 프로그램에서 정책 재사용하기
일반 사용자는 프로그램별 한 번 실행 방식을 권장합니다. 정책을 수동으로 한 번 설정한 뒤 여러 명령에서 재사용해야 한다면 다음 순서로 실행할 수 있습니다.
sudo mudfish-exclude --setup
sudo mudfish-exclude --no-setup discord
sudo mudfish-exclude --no-setup firefox
모든 프로그램을 종료한 뒤 반드시 정책을 정리합니다.
sudo mudfish-exclude --cleanup
수동 방식은 자동 정리를 하지 않습니다. 또한 일부 데스크톱 프로그램은 실행 중 systemd의 다른 cgroup으로 이동할 수 있으므로, 이러한 프로그램에는 cgroup 이동을 추적하고 자동 정리하는 기본 한 번 실행 방식이 더 적합합니다.
--cgroup, --mark, --priority, --table 값을 변경했다면 --setup, --no-setup, --cleanup에서 모두 같은 값을 사용해야 합니다. 사용자 지정 값은 시스템의 기존 방화벽 mark 또는 policy routing 규칙과 충돌하지 않아야 합니다.
문제 해결
mudfish-exclude: command not found
실행 파일이 PATH에 포함되지 않은 상태입니다. 다음 명령으로 설치 위치를 찾은 뒤 전체 경로로 실행하십시오.
ls /opt/mudfish/*/bin/mudfish-exclude
sudo /opt/mudfish/6.5.4/bin/mudfish-exclude discord
두 번째 명령의 버전 번호는 설치된 버전에 맞게 바꾸어야 합니다.
network policy setup requires root
네트워크 정책 설정 권한이 없습니다. 명령 앞에 sudo를 붙여 다시 실행하십시오.
sudo mudfish-exclude discord
cgroup v2 is required at /sys/fs/cgroup
현재 시스템이 cgroup v2를 사용하지 않거나 해당 위치에 마운트하지 않았습니다. 다음 명령으로 확인할 수 있습니다.
test -f /sys/fs/cgroup/cgroup.controllers && echo "cgroup v2 사용 가능"
아무것도 출력되지 않으면 배포판의 cgroup v2 활성화 방법을 확인해야 합니다.
iptables rule add failed 또는 cgroup match 오류
iptables가 설치되어 있는지, 커널과 iptables가 cgroup match를 지원하는지 확인하십시오. nftables 기반 배포판에서도 이 도구는 iptables 호환 명령을 직접 사용하므로 정상적인 iptables 호환 계층이 필요합니다.
failed to find the IPv4 default route
main 라우팅 테이블에서 기존 인터넷 회선의 IPv4 기본 경로를 찾지 못한 상태입니다. 다음 명령 결과에 default 경로가 있는지 확인하십시오.
ip -4 route show default table main
기본 경로가 없거나 이미 다른 VPN 인터페이스를 가리키고 있다면 mudfish-exclude가 원래 인터넷 경로를 구성할 수 없습니다.
제외했는데도 공인 IP가 바뀌지 않음
다음을 순서대로 확인하십시오.
- Full VPN 모드가 실제로 연결되어 있고 일반 실행 시 중계 서버 IP가 표시되는지 확인합니다.
- 대상 프로그램의 기존 프로세스와 백그라운드 프로세스를 모두 종료한 뒤 다시 실행합니다.
- IPv6 결과와 혼동하지 않도록
curl -4또는 IPv4 확인 방법을 사용합니다. - 대상 프로그램이 별도 서비스나 이미 실행 중인 런처에 명령을 넘기는 구조인지 확인합니다. 제외 정책은
mudfish-exclude가 새로 만든 프로세스 계보에만 적용됩니다. ip -4 route show default table main의 기본 경로가 실제 인터넷 인터페이스를 가리키는지 확인합니다.
프로그램을 닫았는데 터미널 명령이 끝나지 않음
자식 또는 백그라운드 프로세스가 아직 제외 cgroup에서 실행 중일 수 있습니다. 관련 트레이 아이콘, 런처, 업데이트 프로세스까지 모두 종료하십시오. 기본 실행 방식은 자식 프로세스가 모두 끝날 때까지 기다린 뒤 정책을 정리합니다.
비정상 종료 뒤 네트워크가 이상함
이 도구로 실행한 프로그램을 모두 종료한 뒤 남은 정책을 정리합니다.
sudo mudfish-exclude --cleanup
그 후에도 문제가 계속되면 미꾸라지를 종료하고 시스템의 기본 경로와 iptables 규칙을 점검한 뒤 다시 연결하십시오.
동작 원리
mudfish-exclude는 실행할 프로그램을 별도의 cgroup v2에 넣고, 그 cgroup에서 발생한 IPv4 패킷에 iptables mark를 설정합니다. 해당 mark를 가진 패킷은 별도 policy routing 테이블을 통해 Linux main 라우팅 테이블에서 찾은 기본 경로로 전달되고, 필요한 NAT MASQUERADE가 적용됩니다.
이 과정은 mudrun, mudflow, mudfish, mudwfp_proxy의 설정이나 공유 메모리 상태를 수정하지 않습니다. 제외 정책은 운영체제의 cgroup, iptables, IPv4 policy routing 계층에서만 동작합니다.