acme_server 지시문

원문 보기 위키 갱신 2026.10.03

acme_server 지시문 (내장 ACME 서버)

acme_server 지시문은 내장된 ACME 프로토콜 서버 핸들러예요. 이를 통해 Caddy 인스턴스가 다른 ACME 호환 소프트웨어(다른 Caddy 인스턴스 포함)를 위해 인증서를 발급할 수 있어요.

출처: Caddy 공식 문서

본문

내장된 ACME 프로토콜 서버 핸들러예요. 이 덕분에 Caddy 인스턴스가 다른 ACME 호환 소프트웨어(다른 Caddy 인스턴스 포함)를 위해 인증서를 발급할 수 있어요.

활성화하면 /acme/* 경로와 일치하는 요청은 ACME 서버가 처리해요.

ACME 서버는 디스크에 데이터베이스를 유지하며, 한 번에 하나의 프로세스만 열 수 있어요. 따라서 Caddy가 이미 이 config를 서빙하는 동안 caddy validate를 실행하면 validate가 실제로 모듈을 프로비저닝하기 때문에 데이터베이스 타임아웃으로 실패해요. Caddy를 시작하기 전에 validate를 실행하거나, caddy reload를 사용해 실행 중인 인스턴스에 대해 config를 확인해요. reload는 실행 중인 프로세스 안에서 새 config를 프로비저닝하므로 데이터베이스를 두고 경쟁하지 않아요. 프로비저닝이 실패하면 활성 config가 계속 실행되고, 성공하면 새 config가 적용돼요.

클라이언트 설정 (Client configuration)

ACME 서버 기본값을 사용하면, ACME 클라이언트는 ACME 엔드포인트로 https://localhost/acme/local/directory를 사용하도록 설정하면 돼요. (local은 Caddy 기본 CA의 ID예요.)

문법 (Syntax)

acme_server [<matcher>] {
	ca         <id>
	lifetime   <duration>
	resolvers  <resolvers...>
	challenges <challenges...>
	allow_wildcard_names
	allow {
		domains <domains...>
		ip_ranges <addresses...>
	}
	deny {
		domains <domains...>
		ip_ranges <addresses...>
	}
}

ca는 인증서에 서명할 인증 기관(CA)의 ID를 지정해요. 기본값은 local로, Caddy의 기본 CA이자 로컬에서 사용하는 자체 서명 인증서용이며, 주로 개발 환경에서 가장 흔해요. 더 넓은 용도로는 혼동을 피하기 위해 다른 CA를 지정하는 것을 권장해요. 주어진 ID의 CA가 이미 없으면 생성돼요. 대체 CA를 구성하려면 PKI 앱 전역 옵션을 참고해요.
lifetime(기본값: 12h)은 발급된 인증서의 유효 기간을 지정하는 duration이에요.

⚠️ 이 값은 서명에 사용되는 중간 인증서의 renewal_window_ratio × intermediate_lifetime보다 작아야 해요.

꼭 필요한 경우가 아니면 바꾸지 않는 것을 권장해요. 높인다면 부등식이 성립하도록 intermediate_lifetime도 그에 맞게 높여요.

중간 인증서는 유효 기간의 renewal_window_ratio × intermediate_lifetime만큼 남았을 때 교체되며, 그 교체 직전에 발급(또는 갱신)된 리프 인증서는 기존 중간 인증서를 서명자로 상속해요. 리프의 lifetime이 그 시점의 중간 인증서 남은 유효 기간을 초과하면, 리프가 자신의 서명 중간 인증서보다 오래 살게 돼요. 그러면 리프 자체가 여전히 유효하더라도 그 중간 인증서가 만료되는 즉시 서빙 체인이 무효가 돼요. 리프가 갱신될 때까지 말이에요.
resolvers는 ACME DNS 챌린지를 해결할 때 TXT 레코드를 조회하는 데 사용할 DNS 해석기 주소예요. 네트워크 주소를 받으며, 지정하지 않으면 기본적으로 UDP, 포트 53이에요. 호스트가 IP 주소면 업스트림 서버를 해석하기 위해 직접 다이얼돼요. 호스트가 IP 주소가 아니면 Go 표준 라이브러리의 이름 해석 규칙으로 주소를 해석해요. 여러 해석기를 지정하면 하나를 무작위로 골라요.
challenges는 활성화할 챌린지 유형을 설정해요. 설정하지 않거나 값 없이 지시문을 쓰면 모든 챌린지 유형이 활성화돼요. 허용되는 값: http-01, tls-alpn-01, dns-01.
allow_wildcard_names는 와일드카드 SAN(주체 대체 이름)이 있는 인증서 발급을 활성화해요.
allow, deny는 acme_server의 운영 정책을 설정해요. 정책 평가는 Step-CA가 여기에서 설명하는 기준을 따라요.
domains는 정책 평가 기준에 따라 허용하거나 거부할 주체 도메인 이름을 설정해요.
ip_ranges는 정책 평가 기준에 따라 허용하거나 거부할 주체 IP 범위를 설정해요.

예시 (Examples)

acme.example.com 도메인에 ID home인 ACME 서버를, pki 글로벌 옵션으로 커스터마이즈된 CA와 함께, internal 발급자를 사용해 자체 인증서를 발급하며 서빙하려면:

{
	pki {
		ca home {
			name "My Home CA"
		}
	}
}

acme.example.com {
	tls {
		issuer internal {
			ca home
		}
	}
	acme_server {
		ca home
	}
}

다른 Caddy 서버가 있다면 위 ACME 서버를 사용해 자체 인증서를 발급할 수 있어요:

{
	acme_ca https://acme.example.com/acme/home/directory
	acme_ca_root /path/to/home_ca_root.crt
}

example.com {
	respond "Hello, world!"
}

더 알아보기 (Learn more)

Caddy 공식 문서