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

이 글 미리 보기

.conf를 수정할 때는 먼저 섹션별 역할을 확인한 다음 Config에서 실제로 선택된 파일을 확인하세요. General에는 공통 매개변수를, Rule에는 연결 정책을, Host에는 정적 이름 매핑을, URL Rewrite에는 조건에 맞는 URL 처리 규칙을 작성합니다. 서버 정보를 이미 보유하고 설정을 읽거나 관리하려는 사용자를 위한 글입니다. 예시는 문법 설명용이며, 실제로 사용할 수 있는 서버 정보가 아니므로 기존 설정을 백업하는 절차도 대체하지 않습니다.

1. 설정 파일 구조: 섹션은 실행 순서가 아닙니다

Shadowrocket의 .conf는 텍스트 형식의 설정 파일입니다. 대괄호로 감싼 이름은 설정 섹션을 구분합니다. 예를 들어 [General]이 나오면 다음 섹션 이름이 나타날 때까지 이어지는 행이 해당 섹션에 속합니다. 섹션마다 문법이 다릅니다. 공통 매개변수와 정적 매핑에는 보통 등호를 사용하고, Rule에서는 키워드·일치 조건·정책을 쉼표로 구분합니다.

이 글에서는 네 섹션만 다루지만, 모든 설정 파일에 이 네 섹션만 있는 것은 아닙니다. 기존 파일을 살펴볼 때 익숙하지 않은 다른 섹션도 그대로 두세요. 예시에 맞추려고 삭제하지 않는 것이 좋습니다. 파일에서 섹션이 나열된 순서는 네트워크 요청 처리 순서와도 다릅니다. 따라서 “Host가 Rule 뒤에 있다”는 이유만으로 트래픽을 먼저 분기한 뒤 이름을 해석한다고 볼 수 없습니다.

4개 섹션

이 글에서 다루는 섹션: General, Rule, Host, URL Rewrite

쉼표 3개

no-resolve가 포함된 IP-CIDR 예시에서 필드를 나누는 쉼표 수

FINAL 1개

이 글의 Rule 예시 끝에 지정한 최종 정책

[General]
dns-server = system

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

[Host]
lab.example.test = 192.0.2.10

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

example.com, example.test, 192.0.2.0/24는 문서 설명을 위한 예시입니다. 정적 매핑에 지정된 주소는 실제 접속에 사용할 서버 주소가 아닙니다. 예시 전체를 일상적으로 사용하는 설정 파일에 그대로 덮어쓰지 마세요. 복사본에서 섹션별로 문법을 확인하는 편이 안전합니다.

2. General: 공통 매개변수와 트래픽 분기 규칙은 다릅니다

[General]에는 공통 설정을 저장합니다. 여기서는 확인하기 쉬운 매개변수 하나만 살펴봅니다: dns-server = system. 등호 왼쪽은 매개변수 이름이고 오른쪽은 값입니다. system은 시스템 DNS를 사용한다는 뜻입니다. 이 설정을 [Rule]에 넣거나, Rule에서 사용하는 쉼표 구분 형식을 적용하지 마세요.

[General]
dns-server = system

[General]: 뒤에 이어지는 내용이 공통 설정 섹션에 속한다고 지정합니다.
dns-server: 설정할 DNS 매개변수입니다.
system: 예시에서 고정된 DNS 서버 주소를 지정하는 대신 현재 시스템이 제공하는 DNS를 사용합니다.

DNS는 도메인 이름을 확인하는 기능이며 서버 연결을 대신하거나 연결이 PROXY와 DIRECT 중 어느 쪽으로 처리될지 단독으로 결정하지 않습니다. 예를 들어 도메인에서 IP 주소를 확인했더라도 서버 연결은 실패할 수 있습니다. 반대로 서버 지연 시간 테스트에 결과가 나와도 현재 DNS가 대상 도메인을 반드시 확인할 수 있다는 뜻은 아닙니다. 문제를 진단할 때는 DNS 조회 결과와 연결 결과를 각각 기록하세요.

3. Rule: 위에서부터 일치 여부를 확인하고 FINAL은 마지막에 둡니다

[Rule]은 트래픽 분기 규칙을 작성하는 섹션입니다. Home → Global Routing에서 Config를 선택한 다음 현재 활성화된 설정의 규칙을 기준으로 일치 결과를 확인하세요. Proxy는 전체 연결에 프록시를 사용하는 모드이고 Direct는 전체 연결을 직접 처리하는 모드입니다. 이 둘로는 방금 수정한 개별 트래픽 분기 규칙을 검증할 수 없습니다. Scene을 사용하는 경우 선택된 Scene과 조건을 먼저 확인해야 하며, Config와 같다고 가정해서는 안 됩니다.

일치 조건

DOMAIN-SUFFIX: example.com,PROXY
IP-CIDR: 192.0.2.0/24,DIRECT,no-resolve
GEOIP: CN,DIRECT

세 행은 각각 도메인 접미사, IP 대역, IP의 지리적 위치를 기준으로 일치 여부를 확인합니다.

정책과 기본 처리

PROXY: 프록시 정책으로 처리합니다. 사용할 수 있는 프록시 출구가 별도로 있어야 합니다.
DIRECT: 프록시 서버를 거치지 않고 대상에 직접 연결합니다.
FINAL: 앞선 규칙에 일치하지 않을 때 지정된 정책을 적용합니다. 예: FINAL,PROXY

REJECT는 일치하는 연결을 거부하는 정책입니다. 직접 연결 정책과 혼동하지 마세요.

DOMAIN-SUFFIX,example.com,PROXY: example.com과 그 하위 도메인(예: www.example.com)에 일치합니다. 문자열 일부가 포함된 임의의 도메인을 대략적으로 찾는다는 뜻은 아닙니다.
IP-CIDR,192.0.2.0/24,DIRECT,no-resolve: 지정된 IPv4 대역에 일치합니다. no-resolve는 이 IP 규칙의 일치 여부를 판단하기 위해 도메인 조회를 새로 시작하지 않는다는 뜻입니다. 앱 전체의 DNS를 끄는 설정은 아닙니다.
GEOIP,CN,DIRECT: IP 지리 정보 데이터를 기준으로 CN에 해당하는지 확인합니다. 도메인 접미사 또는 서버 정보에 표시된 지역을 기준으로 판단하는 것이 아닙니다.
FINAL,PROXY: 앞선 규칙에 일치하지 않은 연결을 PROXY로 처리합니다. 정책만 지정하며 도메인이나 IP 대역 조건은 없습니다.

연결이 앞선 규칙에 일치하면 이후 규칙으로 정책을 다시 선택하지 않습니다. 따라서 구체적인 예외는 적용 범위가 넓은 규칙보다 앞에 두고 FINAL은 마지막에 배치하세요. 앞선 규칙에 이미 일치한 연결은 파일 맨 아래에 예외 규칙을 추가해도 결과가 바뀌지 않습니다.

정리: 규칙 모드를 확인한 뒤 순서를 조정하세요

규칙이 올바르게 보이는데 예상대로 동작하지 않는다면 먼저 Home → Global Routing이 Config로 설정되어 있는지 확인하세요. 그런 다음 현재 파일과 처음으로 일치할 가능성이 있는 규칙을 살펴보세요. 같은 도메인 규칙을 반복해서 추가하는 것부터 시작하지 마세요.

4. Host: 정적 이름 매핑은 정책을 선택하지 않습니다

[Host]는 지정된 호스트 이름을 지정된 주소에 연결하며, 대상 주소를 이미 알고 있는 경우에 사용합니다. Host가 답하는 것은 “이 이름에 어떤 주소를 연결할 것인가?”이지 “이번 연결을 어떤 출구로 처리할 것인가?”가 아닙니다. Host에서 주소를 지정하더라도 처리 방식은 현재 라우팅 모드와 관련 규칙을 함께 확인해야 합니다.

[Host]
lab.example.test = 192.0.2.10

lab.example.test는 전체 호스트 이름입니다. 하위 도메인에 와일드카드 매핑을 적용한다는 내용은 포함되어 있지 않습니다.
호스트 이름과 주소는 =로 구분합니다. Rule에서 사용하는 쉼표로 바꾸지 마세요.
192.0.2.10은 문서 설명용 주소입니다. 실제로 사용하려면 확인을 마친 대상 주소로 바꾸세요.

정적 주소는 대상 서비스의 변경에 따라 더 이상 유효하지 않을 수 있습니다. 특히 동적으로 연결 대상을 배정하는 서비스에서 주의해야 합니다. 문제가 발생하면 Host 항목을 계속 추가하기보다 설정 복사본에서 해당 매핑을 삭제한 뒤 다시 연결해 차이가 있는지 확인하세요.

5. URL Rewrite: URL을 바꾸며 프록시는 선택하지 않습니다

[URL Rewrite]는 조건에 일치하는 URL을 재작성하는 데 사용합니다. Rule은 연결 정책을 선택하고 URL Rewrite는 요청 URL을 처리한다는 점이 다릅니다. 도메인 트래픽 분기 규칙을 그대로 이 섹션에 넣거나 재작성 규칙으로 프록시 서버 매개변수를 대신할 수 없습니다.

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

필드	예시	설명
일치 표현식	`^http://example\.com/`	지정된 HTTP 주소로 시작하는 URL에 일치합니다. 점 앞의 백슬래시는 점 문자를 그대로 찾기 위한 것입니다.
대상 URL	`https://example.com/`	이 예시에서는 고정된 대상 주소를 사용하며 경로 캡처와 재삽입은 다루지 않습니다.
동작	`302`	임시 리디렉션을 반환하여 클라이언트가 대상 URL로 후속 요청을 보내도록 합니다.

이 규칙은 일반 HTTP에만 일치하도록 구성되어 있습니다. 원래 URL에 경로나 쿼리 매개변수가 있더라도 대상 필드에서 캡처 그룹을 참조하지 않으므로 자동으로 유지되지 않습니다. 경로를 보존하려면 먼저 정규식의 캡처 범위를 정하고 결과를 항목별로 확인하세요. 리디렉션 후 로그인 콜백이나 쿼리 매개변수가 사라지지 않도록 주의해야 합니다.

이 예시를 “모든 HTTPS 주소를 경로별로 재작성할 수 있다”는 의미로 확대 해석하지 마세요. HTTPS 요청의 URL을 확인하는 데는 MITM과 같은 추가 조건이 필요하며 앱 동작과 인증서 방식의 영향도 받습니다. 이 글에서는 MITM을 활성화하거나 인증서를 설치하지 않으며, 이 섹션의 필드 구조만 설명합니다.

전체 도메인을 대상으로 하는 표현식부터 만들지 말고, 명확한 테스트 URL 하나로 일치 여부를 확인하세요.
리디렉션 반복을 피하려면 대상 URL이 같은 리디렉션 조건에 다시 일치하지 않도록 하세요.
브라우저가 HTTP를 자동으로 HTTPS로 업그레이드하거나 캐시를 사용할 수 있습니다. 리디렉션을 확인하지 못했다면 먼저 실제 요청 주소를 확인하세요.

6. Config에 적용하기: 파일 저장, 선택, 연결 다시 확인

편집을 마쳤다고 해서 현재 연결에 새 설정이 바로 적용되는 것은 아닙니다. Config에 로컬 파일과 원격 설정이 여러 개 있을 수 있으므로 실제로 선택된 파일을 확인해야 합니다. 파일 이름이 비슷하다면 테스트용 복사본에 알아보기 쉬운 이름을 붙이고 원본 파일은 되돌릴 때를 위해 보관하세요.

원본 파일 백업복사본 수정저장 후 선택모드 확인다시 검증

Config로 이동해 현재 활성화된 파일 이름을 기록하고 원본 파일의 복사본을 보관하세요. 수정할 파일의 편집 화면을 열고 섹션 이름과 수정할 행을 확인합니다.
한 번에 한 섹션에서 소량의 내용만 수정하세요. 저장한 다음 Config로 돌아와 변경 내용이 실제로 저장되었는지 확인하고 테스트할 설정을 선택합니다.
Home → Global Routing으로 돌아가 Config를 선택하세요. Scene을 사용하는 경우 먼저 선택된 Scene을 확인하고, 별도로 검증하려면 일시적으로 Config로 바꿀지 결정하세요.
Home에서 사용할 수 있는 서버가 선택되어 있는지 확인하세요. PROXY는 정책 이름일 뿐이며 서버 주소, 포트 또는 인증 정보가 자동으로 생기지는 않습니다.
네트워크가 잠시 끊겨도 괜찮은 경우 연결 스위치를 껐다가 다시 켠 뒤 대상 요청을 새로 보내세요. 기존의 장시간 연결은 계속 재사용될 수 있으므로 변경 전에 열어 둔 페이지만 관찰해서는 안 됩니다.
요청 기록에서 대상 도메인, 대상 IP, 정책 결과를 확인하세요. 동작이 예상과 다르면 원래 설정으로 복원한 뒤 같은 테스트를 반복해 차이가 이번 변경에서 비롯됐는지 확인합니다.

서버 구독과 .conf 설정 파일도 구분해야 합니다. 전자는 일반적으로 서버 정보를 관리하고, 후자는 규칙과 공통 설정을 관리합니다. 서버 구독을 업데이트해도 Config에서 활성화된 파일이 바뀌는 것은 아닙니다. 원격 설정을 다시 가져오면 해당 파일에 직접 작성한 변경 사항이 덮어써질 수도 있습니다. 장기적으로 관리하기 전에 원격에서 가져온 파일과 직접 관리하는 로컬 복사본이 각각 무엇인지 확인하세요.

정리: 되돌릴 수 있는 단일 변경으로 설정을 검증하세요

매번 “어느 행을 수정했는지, 어떤 파일을 활성화했는지, 어떤 요청을 테스트했는지” 기록하세요. 수정 전후의 동일한 요청에서 설명 가능한 차이가 확인된 경우에만 해당 변경을 일상적으로 사용하는 설정에 반영하세요.

7. 자주 묻는 질문: 증상에 따라 설정 섹션 찾기

Rule을 수정했는데 왜 모든 웹사이트가 같은 방식으로 연결되나요?

먼저 Home → Global Routing에서 Config가 선택되어 있는지 확인한 다음 Config에서 활성화된 파일을 확인하세요. 여전히 결과가 같다면 Rule 상단에 적용 범위가 지나치게 넓은 규칙이 있는지, FINAL이 너무 일찍 나오는지 살펴보세요. 새 요청을 보내 검증하고 기존 장시간 연결을 새로 고치는 데 그치지 마세요.

Host에 주소를 입력했는데 HTTPS 오류가 계속 발생하는 이유는 무엇인가요?

해당 주소에서 대상 호스트 이름에 맞는 서비스를 실제로 제공하는지, 인증서가 해당 도메인에 유효한지 확인하세요. Host는 이름 매핑만 변경합니다. 복사본에서 해당 행을 삭제해 비교하고, 주소 입력 오류를 인증서 검증 완화로 감추지 마세요.

URL Rewrite를 저장했는데도 리디렉션이 보이지 않는 이유는 무엇인가요?

실제 요청이 예시의 HTTP 주소로 시작하는지 확인한 다음 정규식의 백슬래시, 공백으로 구분된 필드, 마지막 동작을 점검하세요. 브라우저가 요청을 보내기 전에 이미 HTTPS로 업그레이드했다면 HTTP에만 일치하는 이 규칙은 적용되지 않습니다.

업데이트 후 직접 수정한 규칙이 사라졌다면 무엇을 확인해야 하나요?

먼저 Config에서 현재 선택된 파일을 확인한 다음 원격 설정을 다시 가져왔는지 살펴보세요. 미리 보관해 둔 로컬 복사본과 비교하고 필요한 변경 사항만 옮기세요. 서버 구독 업데이트와 설정 파일 업데이트를 같은 작업으로 취급하지 마세요.

설정을 더 조정하기 전에 규칙 참고에서 키워드를 확인하거나 설정 안내에서 라우팅 모드와 다른 기능을 구분해 보세요. Settings → On Demand에서는 필요 시 연결 조건을 관리합니다. Config 파일 선택을 대신하거나 Rule 각 행의 작성 형식을 바꾸지는 않습니다.