Shadowrocket 설정 파일 구조와 사용법: .conf의 General·Rule·Host·URL Rewrite 설명

이 글의 핵심 내용

Shadowrocket의 .conf 파일은 연결 환경, 규칙 매칭, 정적 도메인 매핑, URL 재작성을 설정합니다. 직접 사용할 연결 설정이 있고 라우팅 동작을 수정하려는 사용자를 위한 안내입니다. 먼저 네 가지 섹션을 확인하고, 간단한 예제로 문법을 살펴본 뒤 Config에서 수정한 파일을 선택하고 Home에서 실제 적용 결과를 확인합니다. 연결 매개변수와 라우팅 파일은 따로 점검해야 합니다. 파일을 저장했다고 해서 해당 파일로 전환된 것은 아닙니다.

1. 설정 파일과 연결 매개변수 구분하기

Home, Config, Settings는 각각 다른 항목을 관리합니다. Home에서는 기존 연결을 선택하고 연결 상태와 Global Routing을 확인합니다. Config에서는 설정 파일과 규칙을 관리합니다. Settings에는 Settings → On Demand의 자동 연결 조건 같은 앱 설정이 있습니다. 문제를 살펴볼 때는 먼저 바꾸려는 것이 연결 시점인지, 연결 대상인지, 특정 요청의 처리 방식인지 구분하세요.

일반적인 구독 업데이트는 연결 항목을 관리하며, 현재 .conf의 Rule 섹션 업데이트와는 다릅니다. 설정 파일을 원격으로 업데이트하면 로컬 수정 사항이 덮어써질 수도 있으므로 편집 전에 로컬 사본을 보관하세요. 이 글은 이미 사용할 서비스와 구독을 보유한 사용자를 전제로 파일 구조와 확인 방법만 설명합니다.

섹션	주요 역할	대신할 수 없는 항목
`[General]`	DNS, IPv6 등 기본 동작 설정	특정 도메인의 라우팅 규칙
`[Rule]`	도메인, IP 등의 조건에 따라 정책 선택	연결 항목의 인증 매개변수
`[Host]`	지정 도메인에 정적 주소 매핑 설정	서버 측 인증서 및 사이트 설정
`[URL Rewrite]`	URL 매칭 후 리디렉션 등의 동작 수행	트래픽을 PROXY로 보내는 라우팅 규칙

대괄호 안의 섹션 이름은 문법 요소이므로 영문 표기를 유지해야 합니다. 일반적으로 읽기 쉽도록 General, Rule, Host, URL Rewrite 순으로 작성합니다. 네 섹션이 차례로 실행되는 단계별 절차라는 뜻은 아닙니다. 특히 순서에 주의해야 하는 것은 Rule 안의 규칙입니다. 파일 전체가 첫 섹션부터 마지막 섹션까지 순서대로 실행된다고 이해하지 마세요.

2. General: 기본 연결 동작

General은 보통 ‘키 = 값’ 형식으로 작성합니다. 수정할 때는 반각 문장 부호를 유지하고 불리언 값은 true 또는 false로 입력하세요. 필드 값 뒤에 한국어 설명을 붙이면 안 됩니다. 아래 예시는 각 항목을 이해하기 위한 것이며, 모든 사용자가 기존 설정을 덮어써야 하는 공통 템플릿은 아닙니다.

[General]
bypass-system = true
dns-server = system
ipv6 = false

General 항목

bypass-system: true: 시스템 관련 트래픽에 대한 앱의 우회 처리를 유지합니다.
dns-server: system: 현재 네트워크에서 제공하는 시스템 DNS를 사용합니다.
ipv6: false: 설정에서 IPv6 지원을 끕니다. 통신사의 네트워크 문제를 해결해 주지는 않습니다.

기존 값을 기록하고 한 번에 필드 하나만 수정한 다음 같은 대상을 반복해서 테스트하세요.

Rule 키워드

DOMAIN-SUFFIX: 전체 도메인 접미사와 하위 도메인을 기준으로 매칭합니다.
IP-CIDR: IPv4 주소 대역을 기준으로 매칭합니다.
FINAL: 앞선 규칙에 매칭되지 않은 요청을 처리합니다.

General은 기본 동작을 정의하고 Rule은 요청에 적용할 정책을 결정합니다. 서로를 대신할 수 없습니다.

dns-server = system으로 설정해도 현재 네트워크의 DNS를 반드시 사용할 수 있는 것은 아닙니다. 이는 DNS 조회에 사용할 경로를 지정할 뿐입니다. 도메인에 접속할 수 없지만 연결 테스트에는 응답이 있다면 Rule의 최종 정책만 바꾸지 말고 먼저 DNS 조회 결과를 확인하세요. 연결 테스트에서 지연 시간이 표시되어도 대상 사이트의 DNS, TLS, HTTP 요청이 모두 정상이라는 뜻은 아닙니다.

ipv6 = false도 모든 웹 문제를 해결하는 설정은 아닙니다. IPv4와 IPv6의 연결 가능 여부, 프록시의 출구 연결, 대상 주소는 서로 다를 수 있습니다. 기존 파일이 현재 네트워크에 맞춰 IPv6를 설정하고 있다면 그 설정을 유지한 채 재현 가능한 오류 대상별로 비교하세요.

3. Rule: 매칭 조건과 정책

Rule은 보통 ‘유형, 매칭 내용, 정책’ 형식이며 각 항목은 반각 쉼표로 구분합니다. 규칙은 일반적으로 위에서 아래로 검사하고, 일치하는 규칙의 정책을 적용합니다. FINAL에는 별도의 매칭 내용이 없으며 마지막에 두어 나머지 요청을 처리합니다. 아래 예시는 지정한 도메인은 PROXY로 보내고, 문서 예시용 IP 대역과 GEOIP가 CN인 주소는 DIRECT로 보내며, 그 외 요청도 DIRECT로 처리합니다.

[Rule]
DOMAIN-SUFFIX,example.com,PROXY
IP-CIDR,192.0.2.0/24,DIRECT,no-resolve
GEOIP,CN,DIRECT
FINAL,DIRECT

DOMAIN-SUFFIX,example.com,PROXY는 example.com과 그 하위 도메인에 매칭됩니다. 이 문자열을 포함하는 모든 도메인에 매칭되는 것은 아닙니다.
IP-CIDR은 IP 주소 대역에 매칭됩니다. 예시의 192.0.2.0/24는 문서용 IP 대역이므로 실제 서비스 네트워크로 사용할 수 없습니다.
no-resolve는 이 IP 규칙을 위해 추가 도메인 조회를 수행하지 않는다는 뜻입니다. 설정 전체의 DNS를 끄는 기능은 아닙니다.
GEOIP,CN,DIRECT는 대상 IP의 지리 데이터베이스 분류를 기준으로 매칭합니다. 웹페이지 언어, 도메인 접미사 또는 사용자의 현재 위치를 기준으로 판단하지 않습니다.
FINAL,DIRECT는 매칭되지 않은 트래픽을 직접 연결합니다. 이를 FINAL,PROXY로 바꾸면 매칭되지 않은 모든 요청의 경로가 달라집니다.

구체적인 예외 규칙은 보통 범위가 넓은 규칙보다 위에 둡니다. 예를 들어 특정 하위 도메인은 DIRECT로 보내고 같은 기본 도메인의 나머지 요청은 PROXY로 보내려면 DOMAIN,static.example.com,DIRECT를 먼저 쓰고 DOMAIN-SUFFIX,example.com,PROXY를 뒤에 작성하세요. 순서를 바꾸면 하위 도메인이 위쪽 접미사 규칙에 먼저 매칭될 수 있습니다.

4. Host: 정적 도메인 매핑

Host는 ‘도메인 = 주소’ 형식으로 작성하며, 주소가 고정된 경우의 매핑에 사용합니다. Host와 Rule의 역할은 다릅니다. Host는 ‘이 도메인이 어떤 주소로 해석되는가’를 정하고, Rule은 ‘이 요청에 어떤 정책을 적용하는가’를 정합니다. 둘 중 하나를 수정해도 다른 항목이 자동으로 함께 바뀌지는 않습니다.

[Host]
lab.example.com = 192.0.2.10

위 도메인과 주소는 문법 설명을 위한 예시입니다. 192.0.2.10은 문서용 IP 주소이지 실제 서비스 주소가 아닙니다. 실제로 입력할 때는 유효성을 직접 확인한 대상 주소를 사용하고 대상 서버가 해당 도메인의 요청을 올바르게 처리하는지도 확인하세요.

정적 매핑은 대상 사이트의 주소 변경을 자동으로 반영하지 않습니다. 사이트 주소가 바뀌면 연결 실패가 계속될 수 있습니다.
여러 도메인이 같은 IP를 사용한다고 서로 바꿔 쓸 수 있는 것은 아닙니다. HTTPS 연결에서는 도메인, 인증서, 서버의 사이트 설정이 서로 일치해야 합니다.
웹페이지는 이미지, 스크립트, API 도메인에도 요청을 보내는 경우가 많습니다. 기본 페이지의 도메인만 매핑해도 모든 리소스가 같은 주소를 사용하게 되는 것은 아닙니다.
테스트용 매핑을 삭제한 뒤에는 관련 연결을 다시 설정하세요. 이전 연결이 계속 사용되고 있는 결과를 새 설정이 적용되지 않은 것으로 오해하지 않도록 주의하세요.

인증서 오류가 발생해도 검증을 꺼서 잘못된 매핑을 감추지 마세요. 먼저 추가한 Host 행을 삭제해 기존 조회 결과를 복원한 다음 대상 도메인의 인증서와 서버 주소를 확인하세요. 주소가 자주 바뀌는 공개 사이트를 장기간 고정 주소로 설정하면 관리 부담이 커질 수 있습니다.

5. URL Rewrite: 재작성과 라우팅 구분하기

URL Rewrite는 URL 매칭 표현식을 기준으로 지정된 동작을 수행하며, DOMAIN-SUFFIX 같은 Rule 문법을 사용하지 않습니다. 다음 예시는 정규식으로 HTTP 주소를 매칭한 뒤 HTTPS 주소로 302 리디렉션합니다. 구조를 설명하기 위한 예시이며 실제 서비스에 바로 적용할 규칙은 아닙니다.

[URL Rewrite]
^http://example\.com/ https://example.com/ 302

여기서 ^는 URL의 시작 부분부터 매칭한다는 뜻이고 \.은 마침표 문자 자체를 나타냅니다. 마지막의 302는 리디렉션 상태 코드입니다. 이 간단한 예시는 매칭된 요청을 고정 주소로 리디렉션하며 원래 요청의 경로와 쿼리 매개변수를 유지하지 않습니다. 매개변수 보존이 필요한 로그인, 결제, API 요청에는 사용하지 마세요.

확인 항목	Rule	URL Rewrite
매칭 대상	도메인, 대상 IP 등의 조건	처리 대상이 되는 요청 URL
결과 예시	DIRECT 또는 PROXY 적용	302 응답 후 다른 URL로 이동
자주 발생하는 오류	범위가 넓은 규칙이 먼저 매칭됨	정규식 범위가 너무 넓거나 경로가 사라지거나 리디렉션이 반복됨

HTTPS의 전체 경로와 쿼리 매개변수는 암호화된 요청 안에 있으므로 일반적인 라우팅만으로는 확인할 수 없습니다. HTTPS 요청 내용을 확인하는 재작성 작업에는 별도의 HTTPS 복호화 설정, 인증서 신뢰, 도메인 범위 관리가 필요합니다. URL Rewrite 한 줄을 추가하는 것만으로 처리할 수 없습니다. 라우팅만 확인하려는 경우 이 예시를 위해 HTTPS 복호화를 추가로 설정할 필요는 없습니다.

6. 저장한 파일을 Config에서 적용하기

편집이 끝나면 ‘파일이 제대로 저장되었는지’와 ‘현재 해당 파일을 사용 중인지’를 모두 확인해야 합니다. 목록에 파일이 보이는 것은 파일이 있다는 뜻일 뿐입니다. Home의 Global Routing이 Proxy 또는 Direct로 설정되어 있다면 접속 결과만으로 Rule이 예상대로 동작한다고 판단할 수 없습니다. 다음 절차는 기존 파일을 소규모로 수정할 때 적합합니다.

원본 파일 보관하기

Config로 이동해 현재 선택된 파일을 기록하고 로컬 사본을 먼저 보관하세요. 파일이 원격 업데이트에서 온 것이라면 별도의 사본으로 수정하고 테스트해야 다음 업데이트에서 변경 사항이 덮어써지는 일을 막을 수 있습니다.
사본 편집하기

Config에서 사본의 편집 화면을 열고 대상 섹션 하나만 수정하세요. 대괄호, 반각 쉼표, 등호, 정책 이름을 확인한 뒤 저장하고 파일을 다시 열어 내용을 검토하세요.
설정 파일 선택하기

Config의 파일 목록으로 돌아가 수정한 파일을 선택하세요. 선택 표시가 원본이나 이름이 비슷한 다른 원격 파일이 아니라 사본에 표시되는지 확인합니다.
라우팅 모드 전환하기

Home → Global Routing → Config로 이동해 Home에서 선택한 연결 항목을 확인하세요. 필요한 경우 다시 연결해 이후 요청에 새 설정을 적용합니다.
요청 확인하기

먼저 Home → Connectivity Test에서 연결을 확인한 다음 같은 대상에 다시 접속하세요. 연결 기록에서 도메인, 매칭된 규칙, 정책을 확인하고 문제가 생기면 원본 파일로 복원해 다시 테스트합니다.

Config

권장

현재 선택한 설정에 따라 라우팅합니다. Rule 순서, DOMAIN-SUFFIX, FINAL을 확인하려면 먼저 이 모드가 선택되어 있는지 확인하세요.

적합한 경우: 이 문서의 설정 변경 사항과 일상적인 규칙 라우팅을 확인할 때

Proxy

앱이 처리하는 트래픽 중 우회되지 않은 항목에 프록시를 적용합니다. Rule의 일반적인 라우팅 결과에 따라 개별 선택하지 않습니다. 시스템 우회 같은 기본 동작은 별도로 고려해야 합니다.

적합한 경우: 연결 문제와 라우팅 오류를 구분하기 위해 연결 가능성을 일시적으로 비교할 때

Direct

직접 연결 모드를 적용합니다. 이때 대상 사이트가 열려도 현재 직접 연결 경로를 사용할 수 있다는 뜻일 뿐, PROXY 항목이나 지정된 프록시 규칙이 정상이라는 의미는 아닙니다.

적합한 경우: 같은 대상의 직접 연결 결과를 비교해 문제 범위를 좁힐 때

현재 Scene을 사용 중이라면 해당 Scene에 연결된 설정과 정책을 먼저 확인하세요. 파일 이름만 보고 적용 범위를 추측하지 마세요. 변수를 줄이려면 이 문서의 규칙을 처음 확인할 때 명확한 Config 모드를 사용할 수 있습니다. On Demand는 자동 연결 조건을 관리하며 특정 도메인이 어떤 Rule에 매칭되는지는 결정하지 않습니다.

7. 자주 묻는 질문과 설정 복원 확인

FINAL을 수정했는데도 사이트가 기존 경로로 연결되는 이유는 무엇인가요?

먼저 Home → Global Routing이 Config인지 확인하고 Config에서 선택된 파일도 점검하세요. FINAL은 앞선 규칙에 매칭되지 않은 요청만 처리합니다. 이미 DOMAIN-SUFFIX 또는 GEOIP 규칙에 매칭됐다면 FINAL을 수정해도 해당 요청에는 영향이 없습니다. 연결을 다시 설정한 뒤 기록을 확인하세요.

저장할 때 형식 오류가 표시되면 무엇부터 확인해야 하나요?

섹션 이름에 여는 괄호와 닫는 괄호가 모두 있는지, Rule에서 반각 쉼표를 쓰는지, General과 Host에서 등호를 쓰는지 먼저 확인하세요. 이번에 추가한 내용을 잠시 제거해 기존 파일이 저장되는지 확인한 뒤 한 줄씩 다시 추가하세요. 여러 출처의 긴 설정을 한꺼번에 넣지 마세요.

업데이트 후 직접 작성한 규칙이 사라진 이유는 무엇인가요?

먼저 업데이트한 항목이 Home의 구독 항목인지 Config의 원격 파일인지 구분하세요. 원격 파일을 업데이트하면 본문이 교체될 수 있습니다. 보관해 둔 로컬 사본에서 규칙을 복원한 뒤 새로 필요한 내용을 하나씩 병합하세요. 연결 항목 업데이트를 규칙 백업으로 오해하지 않도록 주의하세요.

지연 시간은 표시되지만 웹페이지가 열리지 않습니다. 파일 전체를 다시 작성해야 하나요?

바로 다시 작성할 필요는 없습니다. 이번에 추가한 Host와 URL Rewrite부터 되돌린 다음 DNS 조회 결과, 실제로 매칭된 정책, 대상 연결 상태를 확인하세요. Connectivity Test의 지연 시간은 테스트한 경로에만 해당하며 실제 웹페이지 접속을 대신하지 않습니다. 문제 해결 매뉴얼을 참고해 이어서 점검할 수 있습니다.

신뢰할 수 있는 변경 기록에는 최소한 원본 파일 이름, 수정한 필드, 테스트 도메인, Global Routing 모드, 실제 결과가 포함되어야 합니다. 이 다섯 가지를 기록해 두면 다음에 문제가 생겼을 때 판단 근거를 잃지 않고 변경 사항을 되돌려 재현할 수 있습니다. DNS, 규칙, 연결 항목을 한꺼번에 수정하지 마세요. 관련 개념은 용어 매뉴얼에서 확인하고 연결 문제가 발생하면 연결 문제 해결을 참고하세요.