규약

규약 (Conventions)

출처: Caddy 공식 문서

본문

Caddy 생태계는 플랫폼 전반에서 일관성 있고 직관적으로 만들기 위해 몇 가지 규약을 따르고 있어요.

• 네트워크 주소

• 플레이스홀더

• 파일 위치

• 데이터 디렉터리

• 설정 디렉터리

• 기간(Durations)

네트워크 주소

연결하거나 바인딩할 네트워크 주소를 지정할 때 Caddy는 다음 형식의 문자열을 받아요:

network/address

네트워크 부분은 선택 사항이며(기본값 tcp), Go의 net.Dial함수가 인식하는 무엇이든 될 수 있어요. 네트워크가 지정되면 단일 슬래시 /가 네트워크와 주소 부분을 구분해야 해요.

네트워크는 다음 중 하나일 수 있으며, 4나 6 접미사가 붙은 것은 각각 IPv4 전용, IPv6 전용이에요:

• TCP: tcp, tcp4, tcp6

• UDP: udp, udp4, udp6

• IP: ip, ip4, ip6

• Unix: unix, unixgram, unixpacket

주소 부분은 다음 형태 중 하나일 수 있어요:

• host

• host:port

• :port

• [ipv6%zone]:port

• /path/to/unix/socket

• /path/to/unix/socket|0200

호스트는 어떤 호스트 이름, 해석 가능한 도메인 이름, 또는 IP 주소일 수 있어요.

IPv6 주소의 경우 주소는 대괄호 []로 감싸야 해요. 영역 식별자(%로 시작)는 선택 사항이며(링크-로컬 주소에 자주 사용됨) 그렇지 않아요.

포트는 단일 값(:8080)이거나 포함 범위(:8080-8085)일 수 있어요. 포트 범위는 단일 주소들로 확장돼요. 모든 설정 필드가 포트 범위를 받는 것은 아니에요. 특수 포트 :0은 사용 가능한 아무 포트나 의미해요.

Unix 소켓 경로는 unix* 네트워크 타입을 사용할 때만 허용돼요. 네트워크와 주소를 구분하는 슬래시는 경로의 일부로 간주되지 않아요.

Unix 소켓을 바인드 주소로 사용할 때, 경로 뒤에 파이프 |로 구분해 파일 권한 모드를 선택적으로 지정할 수 있어요. 기본값은 0200(8진수), 즉 u=w,g=,o=(기호)예요. 앞의 0은 선택 사항이에요.

유효한 예시:

:8080
127.0.0.1:8080
localhost:8080
localhost:8080-8085
tcp/localhost:8080
tcp/localhost:8080-8085
udp/localhost:9005
[::1]:8080
tcp6/[fe80::1%eth0]:8080
unix//path/to/socket
unix//path/to/socket|0200

Caddy 네트워크 주소는 URL이 아니에요. URL은 OSI 모델의 하위 계층과 상위 계층을 결합하지만, Caddy는 특정 애플리케이션과 무관하게 네트워크 주소를 자주 사용하므로 둘을 결합하면 문제가 생겨요. Caddy에서 네트워크 주소는 L3-L5에서 연결하거나 바인딩할 수 있는 리소스를 정확히 가리키지만, URL은 L3-L7을 결합하므로 너무 많아요. 네트워크 주소는 호스트+포트와 경로가 상호 배타적이어야 하지만 URL은 그렇지 않아요. 네트워크 주소는 때때로 포트 범위를 지원하지만 URL은 그렇지 않아요.

플레이스홀더

Caddy의 설정은 플레이스홀더 사용을 지원해요. 플레이스홀더를 사용하는 것은 정적 설정에 동적 값을 주입하는 간단한 방법이에요.

플레이스홀더는 다른 소프트웨어의 변수와 비슷한 개념이에요. 예를 들어 nginx에는 변수($uri, $document_root 같은)가 있는 반면, Caddy의 상당 표현은 {http.request.uri}와 {http.vars.root}예요. Caddyfile에서는 {cookie.*}, {header.*}, {path} 같은 공통 요청 필드에 대한 축약형도 있어요.

플레이스홀더는 양쪽이 중괄호 { }로 둘러싸여 있고 내부에 식별자를 담아요. 예: {foo.bar}. 여는 중괄호는 이스케이프 \{like.this}해서 치환을 막을 수 있어요. 플레이스홀더 식별자는 보통 모듈 간 충돌을 피하기 위해 점으로 네임스페이스화돼요.

어떤 플레이스홀더를 사용할 수 있는지는 컨텍스트에 달려 있어요. 모든 플레이스홀더가 설정의 모든 부분에서 사용 가능한 것은 아니에요. 예를 들어 HTTP 앱은 플레이스홀더를 설정하는데, 이는 HTTP 요청 처리와 관련된 설정 영역에서만 사용 가능해요. 요청이 reverse_proxy핸들러를 통과하면 핸들러가 프록시 전용 플레이스홀더를 여러 개 설정해요. 이 플레이스홀더들은 프록싱 중에도, 그리고 이후에도(예: 응답 헤더를 설정하거나 액세스 로그를 풍부하게 만들 때 handle_response에서) 참조될 수 있어요.

다음 플레이스홀더는 항상 사용 가능해요(전역):

플레이스홀더	설명
{env.*}	환경 변수; 예: {env.HOME}
{file.*}	파일에서 읽은 내용; 예: {file./path/to/secret.txt}
{system.hostname}	시스템의 로컬 호스트 이름
{system.slash}	시스템의 파일 경로 구분자
{system.os}	시스템의 OS
{system.arch}	시스템의 아키텍처
{system.wd}	현재 작업 디렉터리
{time.now}	Go Time 구조체로서의 현재 시간
{time.now.http}	HTTP 헤더에서 사용되는 형식의 현재 시간
{time.now.unix}	초 단위 unix 타임스탬프로서의 현재 시간
{time.now.unix_ms}	밀리초 단위 unix 타임스탬프로서의 현재 시간
{time.now.common_log}	Common Log Format의 현재 시간
{time.now.year}	YYYY 형식의 현재 연도

모든 설정 필드가 플레이스홀더를 지원하는 것은 아니지만, 기대되는 대부분의 곳에서 지원돼요. 플레이스홀더 지원은 해당 필드에 명시적으로 추가되어야 해요. 플러그인 작성자는 이 문서를 읽고 자신의 모듈에 플레이스홀더 지원을 추가하는 방법을 배울 수 있어요.

파일 위치

이 섹션은 다양한 파일을 어디서 찾을 수 있는지에 대한 정보를 담고 있어요. 여기 설명된 파일/디렉터리 경로는 기껏해야 기본값이에요. 일부는 덮어쓸 수 있어요.

여러분의 설정 파일

설정 파일을 놓을 단일하고 관례적인 공간은 없어요. 가장 의미가 있는 곳에 두면 돼요.

유일한 예외는 현재 작업 디렉터리의 Caddyfile이라는 파일일 수 있는데, caddy 명령이 다른 설정 파일이 지정되지 않았을 때 편의를 위해 시도하는 파일이에요.

기본 설정 파일과 함께 배포되는 배포판은 설정 파일이 어디 있는지 문서화해야 해요. 패키지/배포판 관리자에게는 명백해 보일 수 있어도요. 대부분의 Linux 설치에서 Caddyfile은 /etc/caddy/Caddyfile에서 찾을 수 있어요.

데이터 디렉터리

Caddy는 TLS 인증서와 기타 중요한 자산을 구성된 저장소 모듈이 지원하는(기본값: 로컬 파일 시스템) 데이터 디렉터리에 저장해요.

XDG_DATA_HOME 환경 변수가 설정되어 있으면 $XDG_DATA_HOME/caddy예요.

그렇지 않으면 OS 규약을 따라 플랫폼마다 경로가 달라요:

OS	데이터 디렉터리 경로
Linux, BSD	$HOME/.local/share/caddy
Windows	%AppData%\Caddy
macOS	$HOME/Library/Application Support/Caddy
Plan 9	$HOME/lib/caddy
Android	$HOME/caddy (또는 /sdcard/caddy)

그 외 모든 OS는 Linux/BSD 디렉터리 경로를 사용해요.

데이터 디렉터리는 캐시로 취급하면 안 돼요. 그 내용물은 일시적인 것도, 순수하게 성능을 위한 것도 아니에요. Caddy는 TLS 인증서, 개인 키, OCSP 스테이플, 그 외 필요한 정보를 데이터 디렉터리에 저장해요. 결과를 이해하지 않고 지우면 안 돼요.

이 디렉터리가 영구적이고 Caddy가 쓸 수 있어야 한다는 것이 매우 중요해요.

설정 디렉터리

Caddy가 일부 설정을 디스크에 저장할 수 있는 곳이에요. 가장 주목할 만한 것은 (기본으로) 마지막 활성 설정을 이 폴더에 보존해서 나중에 caddy run --resume으로 쉽게 재개할 수 있게 하는 거예요.

설정 디렉터리는 여러분의 설정 파일을 저장해야 하는 곳이 아니에요. (물론 저장해도 되긴 해요.)

XDG_CONFIG_HOME 환경 변수가 설정되어 있으면 $XDG_CONFIG_HOME/caddy예요.

그렇지 않으면 OS 규약을 따라 플랫폼마다 경로가 달라요:

OS	설정 디렉터리 경로
Linux, BSD	$HOME/.config/caddy
Windows	%AppData%\Caddy
macOS	$HOME/Library/Application Support/Caddy
Plan 9	$HOME/lib/caddy

그 외 모든 OS는 Linux/BSD 디렉터리 경로를 사용해요.

이 디렉터리가 영구적이고 Caddy가 쓸 수 있어야 한다는 것이 매우 중요해요.

기간(Durations)

기간 문자열은 Caddy 설정 전반에 걸쳐 흔히 사용돼요. Go의 time.ParseDuration문법과 같은 형식을 취하며, 단순화를 위해 하루 = 24시간이라 가정하는 d(일)도 사용할 수 있어요. 유효한 단위는:

• ns (나노초)

• us/µs (마이크로초)

• ms (밀리초)

• s (초)

• m (분)

• h (시간)

• d (일)

예시:

• 250ms

• 5s

• 1.5h

• 2h45m

• 90d

JSON 설정에서 기간 값은 나노초를 나타내는 정수일 수도 있어요.

더 알아보기 (Learn more)

• Caddy 공식 문서