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

.conf 설정 파일의 각 섹션을 살펴봅니다. General은 전역 동작, Rule은 트래픽 분기, Host는 로컬 매핑, URL Rewrite는 주소 변경을 담당하며 작성법과 적용 순서를 설명합니다.

이 글의 핵심

Shadowrocket의 .conf 파일은 서버 목록도, 한 줄씩 실행되는 스크립트도 아닙니다. 이미 이용 중인 서버 정보가 있고 설정을 읽거나 수정해야 하는 사용자를 위해, 네 가지 설정 섹션의 역할을 구분하고 규칙 예시와 모드 비교, 확인 절차를 통해 수정할 위치와 저장 후 적용되지 않는 이유를 설명합니다.

1. .conf의 섹션 구조와 범위

설정 파일은 [General]처럼 대괄호로 섹션 이름을 표시합니다. 해당 이름부터 다음 섹션 이름이 나오기 전까지의 내용이 같은 섹션에 속합니다. 섹션마다 문법이 다릅니다. General에는 주로 키-값 쌍, Rule에는 쉼표로 구분된 매칭 규칙, Host에는 호스트 이름과 주소 매핑, URL Rewrite에는 매칭 표현식과 처리 동작이 사용됩니다. 한 섹션의 문법을 다른 섹션에 그대로 옮기면 안 됩니다.

아래는 구조를 이해하기 위한 최소 예시입니다. 프록시 서버 매개변수는 포함하지 않으며, 현재 네트워크에서 사용할 수 있다고 보장하지 않습니다. 설명에 쓰인 두 문서용 도메인은 매칭 동작을 보여 주기 위한 것으로, 실제 서비스 연결 테스트 대상으로 사용하면 안 됩니다. #으로 시작하는 단독 행은 주석이며, 주석은 연결을 만들거나 정책을 변경하지 않습니다.

# 구조 예시: 사용 전에 현재 설정을 백업하세요
[General]
dns-server = system

[Rule]
DOMAIN,example.com,DIRECT
DOMAIN-SUFFIX,example.org,PROXY
FINAL,DIRECT

[Host]
example.com = 192.0.2.10

[URL Rewrite]
^http://example\.org/(.*)$ https://example.org/$1 302
섹션 4개
General / Rule / Host / URL Rewrite가 각기 다른 역할을 담당합니다
정책 3가지
이 글의 규칙 예시에는 PROXY / DIRECT / REJECT를 사용합니다
최종 규칙 1개
예시에서는 FINAL이 Rule의 마지막 행에 있습니다

섹션이 나열된 순서가 요청 처리 순서를 의미하지는 않습니다. Host를 Rule 뒤에 두었다고 먼저 분기한 다음 Host를 조회하는 것은 아닙니다. URL Rewrite를 파일 맨 앞에 옮겨도 모든 네트워크 연결에서 먼저 주소 변경이 실행되지는 않습니다. 각 섹션은 해당 기능에서 읽습니다. 여기서 말하는 ‘위에서 아래로, 일치하면 중단’ 방식의 트래픽 분기는 Rule 내부의 규칙 순서에만 적용됩니다.

2. General: 전역 옵션은 트래픽 분기 규칙이 아닙니다

[General]에는 DNS 관련 옵션처럼 설정 파일 전반에 적용되는 일반 동작이 들어갑니다. 예시의 dns-server = system은 시스템 DNS 설정을 사용한다는 뜻입니다. ‘모든 연결을 직접 연결한다’거나 ‘모든 도메인을 프록시로 보낸다’는 의미가 아닙니다. 연결 정책은 Global Routing, Rule, 현재 사용 가능한 프록시 설정을 함께 확인해야 합니다.

이 섹션을 수정할 때는 옵션 이름을 원문 그대로 유지하고 값의 형식을 확인하세요. 불리언 값, 주소 목록, 텍스트 매개변수는 서로 바꿔 쓸 수 없습니다. 다른 파일을 그대로 적용하려고 섹션 전체를 한 번에 바꾸지 마세요. 기존 설정의 네트워크 예외, DNS 동작 또는 기타 공통 옵션이 달라져 일부 기능에 문제가 생길 수 있으며, 이 경우 명백한 문법 오류가 나타나지 않을 수도 있습니다.

General 확인 사항

섹션 이름
[General]
키 이름 예시
dns-server
값 지정 예시
dns-server = system
확인 대상
현재 선택된 설정 파일의 공통 옵션

각 키의 용도를 먼저 확인한 뒤 수정 여부를 결정하세요. 섹션 위치만으로 우선순위를 추측하지 마세요.

앱 설정의 범위

트래픽 분기 모드
Home → Global Routing
설정 선택
Config → 현재 사용 중인 설정 파일
자동 연결
Settings → On Demand
프록시 매개변수
Home → 사용자가 이미 등록한 서버 항목

On Demand는 연결이 시작되는 조건을 정합니다. Rule을 대체하거나 설정 섹션을 실행하는 스위치는 아닙니다.

흔히 General을 수정한 뒤 Settings → On Demand에서 자동 연결 조건도 바꾸고는, 어느 변경이 결과에 영향을 줬는지 판단하지 못하는 경우가 있습니다. 설정을 확인할 때는 연결 상태와 네트워크 환경을 먼저 고정하세요. 자동 연결 동작은 별도로 테스트해야 합니다. 이 글에서는 Home, Config, Settings 화면을 기준으로 설명하며, 플랫폼에 따라 버튼 배치는 다를 수 있습니다.

3. Rule: 순서대로 매칭하고 FINAL은 마지막에 배치

[Rule]은 조건에 맞는 요청에 적용할 정책을 정합니다. 일반 규칙은 유형, 매칭 값, 정책으로 구성되며 FINAL에는 매칭 값이 필요하지 않습니다. PROXY는 요청을 프록시 경로로 보내고, DIRECT는 직접 연결하며, REJECT는 요청을 거부합니다. PROXY 자체가 사용할 수 있는 서버를 만들어 주지는 않으므로, 사용자가 이미 보유한 연결 가능한 서버 정보가 필요합니다.

[Rule]
DOMAIN,api.example.com,DIRECT
DOMAIN-SUFFIX,example.com,PROXY
IP-CIDR,192.0.2.0/24,DIRECT,no-resolve
GEOIP,CN,DIRECT,no-resolve
FINAL,PROXY
규칙 유형예시의 의미확인할 점
DOMAINapi.example.com이라는 정확한 도메인만 매칭합니다.다른 하위 도메인은 포함하지 않습니다.
DOMAIN-SUFFIXexample.com과 그 하위 도메인을 매칭합니다.더 구체적인 예외 규칙은 이 규칙보다 앞에 배치하세요.
IP-CIDR192.0.2.0/24 주소 범위를 매칭합니다.no-resolve는 해당 규칙만을 위해 도메인 조회를 시작하지 않도록 합니다.
GEOIP주소 위치 데이터베이스를 기준으로 CN에 속하는지 판단합니다.IP 데이터를 기준으로 판단하며, 웹페이지 언어나 도메인 접미사는 기준으로 삼지 않습니다.
FINAL앞선 규칙에 일치하지 않은 요청에 PROXY를 적용합니다.뒤의 규칙을 먼저 가로채지 않도록 맨 마지막에 배치하세요.

위 순서에서는 api.example.com이 먼저 DOMAIN과 일치하므로 DIRECT를 사용합니다. www.example.com은 첫 번째 행과 일치하지 않고 다음 DOMAIN-SUFFIX 규칙에 걸려 PROXY를 사용합니다. 이는 규칙을 바탕으로 예상한 결과이며, 예시 도메인의 실제 네트워크 연결을 테스트한 기록은 아닙니다. 접미사 규칙을 맨 앞에 두면 정확한 도메인에 대한 예외가 적용되지 않습니다.

no-resolve는 앱 전체에서 DNS를 끄는 옵션이 아닙니다. 해당 IP 유형 규칙이 매칭을 위해 직접 DNS 조회를 시작할지 제한합니다. 요청에 이미 IP 주소가 있다면 여전히 규칙과 일치할 수 있습니다. 이 옵션을 사용하면 대상 주소를 아직 확인하지 못한 도메인 요청이 이후 규칙이나 FINAL로 넘어갈 수 있습니다. 모든 주소의 소속 여부가 이미 판정됐다고 가정하지 마세요.

4. Host: 주소 매핑은 연결 정책과 다릅니다

[Host]는 로컬에서 정적 호스트 이름을 매핑할 때 사용합니다. 아래 행은 example.com을 192.0.2.10에 연결합니다. 이 주소는 문서 예시용 주소 범위에 속하며, 여기서 제공하는 서비스 주소가 아닙니다. 실제로 사용할 때는 사용 권한이 있고 올바른지 확인한 대상 주소로 바꿔야 합니다.

[Host]
example.com = 192.0.2.10

‘어디에 연결하는가’와 ‘어떤 경로로 연결하는가’ 구분하기

Host: 주소 매핑
  • 지정한 호스트 이름에 로컬 주소를 매핑합니다.
  • 페이지 주소를 다른 도메인으로 자동 변경하지 않습니다.
  • DIRECT 또는 PROXY를 자동으로 선택하지 않습니다.
Rule: 연결 경로 선택
  • 도메인이나 주소 등의 조건에 따라 정책을 선택합니다.
  • DOMAIN으로 도메인에 적용할 정책을 정확히 지정할 수 있습니다.
  • 웹사이트의 대상 호스트 이름을 단독으로 바꾸지는 않습니다.

주소를 고정하고 연결 경로도 지정해야 한다면 Host와 Rule을 각각 설정한 뒤, 매핑 결과와 정책 매칭을 따로 확인하세요.

Host는 인증서를 수정하는 기능도 아닙니다. HTTPS에 연결할 때 정적 매핑 주소를 사용하더라도 웹사이트는 접속한 호스트 이름과 일치하는 인증서를 제공해야 합니다. 잘못된 서버로 매핑하면 인증서 불일치, 연결 종료, 잘못된 사이트 콘텐츠가 발생할 수 있습니다. 이 경우 인증서 검증을 느슨하게 해서 대상 주소 오류를 가리지 말고 먼저 매핑을 확인하세요.

앱이 IP에 직접 연결하거나 자체적인 주소 조회 방식을 사용하면 일반적인 도메인 요청과 다른 동작을 보일 수 있습니다. 문제를 확인할 때는 실제 요청의 호스트 이름과 대상 주소를 기록하세요. 브라우저 주소 표시줄만 보고 Host가 주소 조회에 반영됐다고 판단해서는 안 됩니다. 기존 연결이 이전 주소를 계속 재사용할 수도 있으므로, 수정 후에는 새 연결로 확인하세요.

5. URL Rewrite: 요청 주소를 매칭하고 동작 지정

[URL Rewrite]는 URL 매칭과 주소 변경을 처리하며, 네트워크 라우팅을 담당하지 않습니다. 아래 예시는 정규식으로 지정된 도메인의 일반 HTTP 주소를 매칭한 뒤 HTTPS 주소로 302 리디렉션합니다. 예시가 http://로 시작하는 것은 일반 HTTP 요청을 볼 수 있음을 설명하기 위해서이며, 모든 HTTPS 요청 내용을 직접 읽을 수 있다는 뜻은 아닙니다.

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

표현식에 따르면 http://example.org/docs의 대상 주소는 https://example.org/docs입니다. 새 요청에는 여전히 주소 조회, 연결 정책 매칭, 연결 설정이 필요합니다. 따라서 Rewrite는 ‘Rule을 우회하는’ 지름길이 아니며, 도달할 수 없는 대상에 새로 연결되게 만들지도 않습니다.

리디렉션이 반복되면 변경된 주소가 같은 규칙이나 다른 규칙의 표현식에 다시 일치하는지 먼저 확인하세요. 경로가 사라지면 캡처 그룹과 $1이 올바르게 대응하는지 확인하세요. 전혀 실행되지 않으면 분기 정책을 바로 수정하기보다 실제 요청이 브라우저에서 이미 HTTPS로 자동 전환됐는지 먼저 확인하세요.

6. Config와 Global Routing: 파일을 선택한 뒤 분기 모드도 확인

Config 화면에서는 설정 파일을 관리하고, Home → Global Routing에서는 현재 사용할 트래픽 분기 모드를 선택합니다. 이름은 비슷해도 역할이 다릅니다. 파일이 Config 목록에 표시된다고 해서 현재 사용 중인 것은 아니며, 파일을 선택했다고 해서 해당 파일의 규칙에 따라 분기하는 모드가 선택된 것도 아닙니다.

Config

권장

현재 설정의 규칙에 따라 연결 정책을 선택합니다. 어떤 규칙에도 일치하지 않는 요청의 처리는 마지막 규칙에 따라 달라집니다. FINAL은 DIRECT일 수도, PROXY일 수도 있으므로 ‘나머지는 모두 직접 연결’이라고 단정할 수 없습니다.

적합한 경우: Rule 순서와 특정 도메인의 트래픽 분기 결과를 확인할 때

Proxy

전역 프록시 모드를 사용하며, Rule에 설정된 일반적인 트래픽 분기 방식에 따라 경로를 선택하지 않습니다. 시스템에서 처리하는 트래픽 범위, 네트워크 예외, 프로토콜 사용 가능 여부의 영향을 받을 수 있습니다.

적합한 경우: 프록시 경로가 작동하는지 잠시 비교할 때. Rule이 적용됐다는 증거로 사용할 수는 없습니다.

Direct

직접 연결 모드를 사용해 로컬 네트워크 경로를 확인합니다. 설정 파일의 PROXY 텍스트를 모두 DIRECT로 바꾸는 기능은 아닙니다.

적합한 경우: 같은 대상이 직접 연결 환경에서 어떻게 동작하는지 비교할 때

Scene

설정된 Scene 조건에 따라 해당 동작으로 전환합니다. 결과는 Scene 정의에 따라 달라지므로 사용 전에 현재 네트워크가 어떤 Scene에 해당하는지 확인하세요.

적합한 경우: Scene 설정이 명확한 환경. 고정된 규칙을 점검할 때는 먼저 이 변수를 줄이세요.

규칙을 테스트할 때 Config를 선택하면 요청 결과를 특정 Rule과 연결해 확인하기 쉽습니다. Proxy로 전환했을 때는 접속되지만 Config로 돌아오면 실패한다면 두 경로 또는 정책 선택이 다르다는 점만 알 수 있습니다. 실제로 일치한 규칙 행, 대상 주소 조회 결과, 사용 가능한 서버를 확인해야 하며, 곧바로 ‘설정 파일이 손상됐다’고 결론 내릴 수는 없습니다.

7. 저장·활성화·문제 해결: 한 번에 변수 하나만 변경

수정 전에 원본 파일을 보관하세요. 원격 주소에서 가져온 설정 파일은 특히 주의해야 합니다. 원격 업데이트가 로컬 수정을 덮어쓸 수 있습니다. 서버 구독 갱신과 설정 파일 업데이트도 서로 다른 작업입니다. 전자는 보통 서버 항목을 갱신하고, 후자는 General이나 Rule 등의 내용을 바꿀 수 있습니다. 구독 갱신에 성공했다고 Rule이 다시 로드됐다고 볼 수는 없습니다.

  1. 복사본 보관

    Config에서 현재 사용 중인 파일을 확인하고, 복구할 수 있는 원본 복사본을 먼저 보관한 다음 해당 파일의 편집 메뉴로 이동하세요. 사용할 수 있는 유일한 설정을 바로 덮어쓰지 마세요.

  2. 한 곳만 수정

    예를 들어 Rule에서 DOMAIN 규칙 한 개의 위치만 조정하세요. General, Host, URL Rewrite는 그대로 두고 수정 전후의 전체 행을 기록합니다.

  3. 활성화 확인

    저장한 뒤 Config로 돌아가 방금 수정한 파일이 선택되어 있는지 확인하세요. 그런 다음 Home → Global Routing에서 Config를 선택하고 연결이 활성화되어 있는지 확인합니다.

  4. 새 요청 보내기

    같은 네트워크에서 대상 요청을 다시 보내고, 요청 기록에서 확인할 수 있는 도메인, 대상 IP, 정책 정보를 살펴보세요. 이전 세션의 영향을 피하려면 연결을 새로 설정하세요.

  5. 복구 후 비교

    예상과 다른 결과가 나오면 원래 행으로 복구한 뒤 다시 테스트하세요. 자동 연결 동작을 확인해야 한다면 여러 설정을 동시에 바꾸지 말고 Settings → On Demand에서 따로 점검하세요.

증상먼저 확인할 항목다음 단계
규칙을 저장해도 정책이 바뀌지 않음현재 선택된 파일과 Global Routing 모드Config를 사용 중인지 확인한 다음, 앞에 더 포괄적인 매칭 규칙이 있는지 살펴보세요.
특정 도메인에서 인증서 오류 발생Host가 잘못된 주소로 매핑되었는지 확인하세요.해당 매핑을 제거하고 새 연결을 만든 뒤 인증서와 대상 호스트 이름을 비교하세요.
URL Rewrite가 실행되지 않음요청의 프로토콜, 도메인, 경로가 표현식과 일치하는지 확인하세요.먼저 일반 HTTP 예시의 동작을 확인한 다음 실제 요청을 확인할 수 있는지 점검하세요.
업데이트 후 사용자 지정 규칙이 사라짐업데이트한 항목이 원격 설정인지 서버 구독인지 확인하세요.백업과 비교해 수정을 복원하고 이후에 관리할 파일의 출처를 명확히 하세요.
PROXY 규칙에 일치했지만 연결 실패이미 등록한 서버의 프로토콜 매개변수와 연결 상태규칙 매칭과 프록시 연결 성공 여부를 분리해 점검하고, Rule 순서를 반복해서 바꾸지 마세요.

최종적으로는 다음 네 가지를 따로 확인해야 합니다. 설정 파일이 선택되어 있는가, 요청이 예상한 규칙과 일치하는가, 조회된 주소가 올바른가, 선택한 경로로 연결할 수 있는가. General, Rule, Host, URL Rewrite는 각각 이 중 서로 다른 부분을 설명하므로 한 섹션을 수정해 전체 문제 해결을 대신할 수는 없습니다. 화면 설정은 설정 안내에서, 프로토콜 필드는 프로토콜 참고 자료에서 확인할 수 있습니다.

Shadowrocket 다운로드