Shadowrocket .conf 설정 파일 구조와 작성법: General, Rule, Host, URL Rewrite

이 글의 핵심

Shadowrocket의 .conf 파일은 대괄호로 표시된 섹션별로 역할이 나뉘며, 서버 구독 목록이 아닙니다. 사용할 서버와 구독을 이미 보유하고 있고 트래픽 분기 설정을 조정하려는 사용자를 위해, 네 가지 섹션을 먼저 구분한 뒤 최소 예제로 하나씩 검증하는 방법을 설명합니다. 마지막으로 활성화 상태, 규칙 순서, 원격 업데이트를 확인해 여러 항목을 한꺼번에 수정했을 때 원인을 찾기 어려운 상황을 방지합니다.

1. 설정 파일, 서버, 실행 모드 구분하기

.conf는 텍스트 설정 파일입니다. 섹션 이름은 보통 한 줄을 차지하며, 다음 섹션 이름이 나올 때까지 이어지는 항목은 해당 섹션에 속합니다. [General]에는 일반적으로 키-값 매개변수가, [Rule]에는 한 줄에 하나씩 매칭 규칙이 들어갑니다. 두 문법은 서로 바꿔 쓸 수 없습니다. dns-server = system을 [Rule]에 넣어도 유효한 도메인 규칙이 되지 않습니다.

Home에서는 서버 선택, 연결 제어, Global Routing 확인을 할 수 있습니다. Config에서는 설정 파일을 관리하고 선택하며, Settings에서는 앱 설정을 관리합니다. 서버 항목은 ‘어떤 출구로 연결할지’를 정하고, 설정 파일은 ‘각 요청에 어떤 정책을 적용할지’를 정합니다. 서버 구독 업데이트가 성공했더라도 Config에서 의도한 규칙 파일이 선택되어 있다는 뜻은 아닙니다.

설정 섹션	담당 내용	대신할 수 없는 내용
`[General]`	DNS 등 전역 동작 매개변수	서버 인증 정보
`[Rule]`	순서대로 매칭해 정책 선택	서버 자체의 사용 가능 여부
`[Host]`	지정 도메인의 로컬 주소 매핑	URL 경로 및 포트 재작성
`[URL Rewrite]`	표현식에 따른 URL 재작성 또는 요청 처리	일반 도메인 트래픽 분기 규칙

[Rule]을 확인할 때는 Home → Global Routing에서 Config를 선택합니다. Proxy와 Direct는 전역 실행 모드이므로 개별 설정 규칙의 매칭 여부를 판단하는 기준이 될 수 없습니다. Scene은 선택한 시나리오 설정에 따라 동작하므로, 문제를 해결할 때는 해당 시나리오에서 사용하는 설정도 확인해야 합니다. 먼저 Config로 고정하면 실행 모드가 바뀌어 생기는 변수를 줄일 수 있습니다.

2. [General]: 설명할 수 있는 전역 매개변수만 유지하기

[General]은 키 = 값 형식으로 작성합니다. 아래 예제를 테스트 설정에 넣을 수 있습니다. dns-server = system은 시스템에서 제공하는 DNS를 사용합니다. bypass-system과 skip-proxy는 시스템 및 지정 주소의 우회 동작과 관련된 옵션이므로, 연결 속도를 높이는 범용 스위치로 사용해서는 안 됩니다.

[General]
dns-server = system
bypass-system = true
skip-proxy = 127.0.0.1, 192.168.0.0/16

127.0.0.1은 루프백 주소이고 192.168.0.0/16은 사설 주소 범위입니다. 예제에는 이 두 범위만 나와 있으며 모든 로컬 네트워크를 포함하는 것은 아닙니다. 로컬 네트워크에서 다른 대역을 사용한다면 먼저 네트워크 주소와 접근 대상을 확인하세요. 지나치게 넓은 우회 범위를 그대로 복사한 뒤 나중에 규칙으로 보완하지 마세요.

General 매개변수 확인

dns-server: system
bypass-system: true
skip-proxy: 127.0.0.1, 192.168.0.0/16

별도의 테스트 예제입니다. 기존 설정에 적용하기 전에 원래 값과 로컬 네트워크 대역을 비교하세요.

Rule 항목 확인

DOMAIN-SUFFIX: example.com,PROXY
IP-CIDR: 192.168.0.0/16,DIRECT,no-resolve
FINAL: PROXY

쉼표로 구분하는 규칙이며 General의 등호 형식은 사용하지 않습니다.

같은 섹션에 동일한 키를 반복해서 추가해 ‘누적’을 표현하지 마세요. 매개변수마다 중복 항목을 처리하는 방식이 다를 수 있으므로, 정리할 때는 명확한 목표 값을 하나만 남겨야 합니다. DNS를 변경하기 전에는 기존 값도 기록해 두세요. 도메인 조회 실패와 프록시 핸드셰이크 실패는 서로 다른 문제이며, 서버를 바꿔도 잘못된 DNS 설정이 자동으로 수정되지는 않습니다.

3. [Rule]: 구체적인 규칙을 앞에, FINAL을 마지막에

Config 모드에서는 규칙을 나열된 순서대로 확인하며, 먼저 일치한 항목이 정책을 결정합니다. 아래 예제는 정확한 도메인, 도메인 접미사, IP 주소 대역, 지역 매칭, 기본 규칙 순으로 보여 줍니다. example.com과 example.org는 문법 설명용 도메인일 뿐이며, 규칙에 서버 주소나 구독 인증 정보는 포함되어 있지 않습니다.

[Rule]
DOMAIN,blocked.example.com,REJECT
DOMAIN-SUFFIX,example.com,PROXY
DOMAIN-SUFFIX,example.org,DIRECT
IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
GEOIP,CN,DIRECT
FINAL,PROXY

DOMAIN은 지정한 도메인과 정확히 일치하는 항목을 찾습니다. 따라서 이 예제의 blocked.example.com은 뒤에 있는 접미사 규칙보다 먼저 REJECT에 매칭됩니다.
DOMAIN-SUFFIX,example.com,PROXY는 해당 도메인과 하위 도메인을 매칭하며, 웹페이지 URL의 경로는 기준으로 삼지 않습니다.
IP-CIDR은 대상 IP가 속한 주소 대역을 기준으로 판단합니다. 추가 옵션인 no-resolve는 이 IP 규칙을 위해 도메인 조회를 능동적으로 실행하지 않는다는 뜻이지, 요청 전체에 DNS가 전혀 필요 없다는 뜻은 아닙니다.
GEOIP,CN,DIRECT는 대상 IP의 지역 데이터에 따라 판단합니다. 도메인 접미사나 운영 주체를 기준으로 판단하지 않습니다.
FINAL,PROXY는 앞선 규칙에 매칭되지 않은 요청을 처리하므로 규칙 맨 끝에 두어야 합니다.

PROXY, DIRECT, REJECT는 정책 키워드이며 프로토콜 세 종류를 가리키는 것이 아닙니다. PROXY를 사용하려면 이용 가능한 프록시 출구가 있어야 합니다. DIRECT는 대상에 직접 연결하고, REJECT는 매칭된 요청을 거부합니다. 설정에서 이름이 지정된 정책 그룹을 사용한다면 규칙에서 참조하는 그룹 이름이 실제로 있는지 확인하세요. 예제의 PROXY를 정의되지 않은 이름으로 임의 변경하지 마세요.

대상 정보순서대로 매칭첫 번째 일치 항목정책 적용연결 기록

핵심: 새 규칙을 추가하기 전에 첫 번째 매칭 규칙부터 확인하세요

특정 하위 도메인에 DIRECT를 적용하려면 해당 도메인의 DOMAIN 규칙을 범위가 넓은 DOMAIN-SUFFIX 규칙보다 앞에 두세요. 수정 후에는 같은 대상을 다시 테스트하고 연결 기록에서 적용된 정책을 확인합니다.

4. [Host]: 도메인과 주소만 매핑하기

[Host]는 보통 도메인 = IP 주소 형식으로 작성합니다. 왼쪽에는 전체 URL이 들어가지 않으며, 오른쪽에도 경로나 포트를 입력하지 않습니다. 아래 예제는 형식 설명을 위해 테스트용으로 예약된 도메인과 문서용 예시 주소를 사용합니다. 별도의 테스트 설정에서 형식을 확인하는 데 활용할 수 있지만, 이 주소들이 실제로 접속 가능한 서비스를 가리키는 것은 아닙니다.

[Host]
portal.example.test = 192.0.2.10
api.example.test = 192.0.2.20

Host 매핑은 주소 조회 결과를 바꿀 뿐, 요청을 자동으로 DIRECT로 전환하지 않습니다. 자체 테스트 도메인을 직접 연결하려면 [Rule]의 적절한 위치에 해당 정책을 별도로 추가해야 합니다. 매핑이 올바르더라도 HTTPS 연결에는 요청 도메인과 일치하는 인증서가 필요합니다. Host 항목만으로 인증서 이름 불일치 문제를 해결할 수는 없습니다.

먼저 서비스가 실제로 수신 대기 중인 주소와 포트를 확인합니다. 예를 들어 테스트 서비스가 443 포트에서 대기 중인지 확인하세요.
Host의 왼쪽에는 도메인만 입력하고 https://나 :443은 적지 않습니다.
Rule에서 해당 도메인에 적용되는 정책을 확인하세요. 주소 조회 결과만 확인해서는 안 됩니다.
대상 주소가 변경되었다면 기존 매핑을 업데이트하거나 삭제한 다음 요청을 다시 보냅니다. 이미 연결된 세션과 앱 캐시 때문에 재테스트 결과가 바로 바뀌지 않을 수 있습니다.

원격 프록시가 대상 도메인 조회에 관여할 수도 있습니다. 이는 송신 방식과 연결 처리에 따라 달라집니다. 따라서 문제를 확인할 때는 요청 대상, 선택된 정책, 실제 연결 결과를 함께 살펴봐야 합니다. 기기에서 한 번 DNS를 조회한 결과만으로 전체 연결 경로가 동일한 주소를 사용한다고 단정할 수 없습니다.

5. [URL Rewrite]: 표현식, 대상, 동작 구분하기

[URL Rewrite]는 URL을 처리하며 프록시 출구를 선택하지 않습니다. 아래 예제는 예시 도메인의 HTTP 요청을 HTTPS로 리디렉션합니다. 매칭 표현식, 대상 주소, 302 동작은 공백으로 구분합니다. $1은 표현식의 첫 번째 캡처 그룹을 가리키며 호스트 이름 뒤의 내용을 유지합니다.

[URL Rewrite]
^http://example\.com/(.*)$ https://example.com/$1 302

예를 들어 http://example.com/docs?a=1을 입력하면 규칙의 대상은 https://example.com/docs?a=1이 됩니다. 여기서 역슬래시는 도메인 이름의 점을 문자 그대로 처리하며, 맨 앞의 ^는 매칭 시작 위치를 제한합니다. 302는 리디렉션 응답을 반환한다는 뜻이며, 이후 HTTPS 요청에는 별도의 연결 및 트래픽 분기 처리가 적용됩니다.

처음에는 도메인 하나만 지정해 명확하게 테스트하세요. 모든 웹사이트에 적용되는 광범위한 표현식부터 작성하지 마세요.
이 예제는 HTTP만 매칭하고 대상은 HTTPS이므로, 대상 URL이 같은 규칙에 다시 매칭되지는 않습니다.
경로를 재작성한다면 슬래시, 캡처 그룹, 쿼리 매개변수를 하나씩 확인해 대상 주소가 잘못 조합되지 않도록 하세요.
이 규칙을 추가해도 기존 HTTPS 요청의 전체 경로가 노출되지는 않습니다. 암호화된 요청 내용을 처리하려면 별도의 조건이 필요하며, 이 글의 예제를 위해 MITM을 설정할 필요는 없습니다.

도메인 트래픽을 분기하려고 URL Rewrite를 추가하지 마세요. example.com에 PROXY를 적용하려면 [Rule]로 돌아가 DOMAIN-SUFFIX를 작성하세요. 자체 테스트 도메인의 조회 주소만 고정하려면 [Host]를 사용합니다. 각 기능의 역할을 분리하면 문제가 생겼을 때 더 쉽게 되돌릴 수 있습니다.

6. 저장, 활성화, 검증: 한 번에 한 섹션만 수정하기

편집하기 전에 Config에서 현재 정상적으로 작동하는 설정을 복사해 두고, Home에서 선택한 서버와 Global Routing도 기록하세요. 서버 구독과 원격 .conf 설정 파일은 업데이트 대상이 다릅니다. 전자는 보통 서버 항목을 업데이트하고, 후자는 설정 파일 내용을 업데이트합니다. 원격 설정에 해당하는 내용을 직접 수정하면 다음 업데이트 때 로컬 변경 사항이 덮어써질 수 있으므로, 먼저 별도의 로컬 복사본을 만들어 테스트하세요.

기준 상태 설정: Home에서 이미 사용할 수 있는 서버를 선택하고 연결한 뒤 Connectivity Test로 기본 연결을 확인합니다. 이 테스트만으로 특정 웹사이트나 규칙이 정상 작동하는지 확인할 수는 없습니다.
복사본 편집: Config에서 테스트할 설정을 열고 해당 섹션을 찾아 매개변수 하나 또는 규칙 하나만 수정합니다. 저장한 다음 설정 목록으로 돌아갑니다.
활성화 여부 확인: Config에서 해당 파일을 선택한 뒤 Home → Global Routing에서 Config를 선택합니다. 필요하다면 새 설정을 이번 검증에 적용하기 위해 다시 연결하세요.
요청 재현: 같은 도메인, 프로토콜, 경로로 새 요청을 보냅니다. Host나 URL Rewrite를 수정한 경우에는 이전 페이지의 캐시를 근거로 판단하지 마세요.
결과 비교: 연결 기록에서 대상과 정책을 확인합니다. 결과가 예상과 다르면 해당 변경 사항을 먼저 되돌린 뒤 수정 전후를 비교하세요.

예를 들어 DOMAIN-SUFFIX를 테스트할 때는 같은 하위 도메인에 접속하고, Host를 테스트할 때는 대상 서비스와 포트를 고정합니다. URL Rewrite를 테스트할 때는 브라우저가 HTTPS로 자동 완성한 주소가 아니라 http://를 입력했는지 확인하세요. ‘요청이 전혀 전송되지 않음’, ‘요청이 잘못된 정책에 매칭됨’, ‘출구 연결 실패’를 구분해 기록하면 DNS, 규칙, 서버를 한꺼번에 바꾸는 것보다 원인을 파악하기 쉽습니다.

7. 자주 묻는 질문: 설정이 맞아 보이는데 적용되지 않는 경우

Rule을 저장했는데 왜 모든 요청이 같은 정책을 사용하나요?

먼저 Home → Global Routing이 Config로 설정되어 있는지 확인한 다음, Config로 돌아가 선택된 파일을 확인하세요. 실행 모드가 Proxy 또는 Direct라면 모드를 먼저 바꾸고 요청을 다시 보내세요. Rule 맨 끝에 같은 항목을 계속 추가하지 마세요.

하위 도메인 규칙을 추가했는데 왜 접미사 규칙에 매칭되나요?

규칙 순서를 확인하세요. 정확히 일치하는 DOMAIN 항목을 해당 도메인을 포함하는 DOMAIN-SUFFIX보다 앞에 옮기고, 그보다 앞에서 먼저 매칭되는 규칙이 없는지 확인합니다. FINAL 뒤에 있는 항목도 FINAL 앞으로 옮겨야 합니다.

Host를 새 주소로 바꿨는데 왜 웹페이지에 오류가 표시되나요?

먼저 주소와 서비스 포트를 확인한 다음 정책과 HTTPS 인증서를 점검하세요. Host는 8443 포트에서 대기 중인 서비스를 자동으로 443 포트로 바꾸지 않습니다. 기본 포트가 아닌 포트를 사용해야 한다면 실제 접속 URL에 포트를 명시하고 연결을 새로 만들어 검증하세요.

업데이트 후 직접 추가한 설정이 사라진 이유는 무엇인가요?

Config에서 방금 업데이트한 항목이 원격 설정인지 로컬 복사본인지 확인하고 이전 백업과 비교하세요. 사용자 지정 규칙을 계속 유지하려면 자체 로컬 설정에서 관리해야 합니다. 원격 설정을 다시 적용하기 전에는 변경 사항을 확인해 기존 내용이 덮어써지지 않도록 하세요.

전체 문법은 규칙 매뉴얼에서 확인할 수 있습니다. 실제 설정에서는 용도를 설명할 수 있는 매개변수만 유지하고, 도메인 트래픽 분기, 주소 매핑, URL 재작성을 각각 분리해 관리하세요. 수정할 때마다 대상, 예상 정책, 되돌릴 설정 파일을 기록해 두면 이후 업데이트 때 다시 확인하기 쉽습니다.