명령줄

원문 보기 위키 갱신 2026.10.03

명령줄 (Command Line)

출처: Caddy 공식 문서

본문

Caddy는 표준 unix 계열 명령줄 인터페이스를 갖고 있어요. 기본 사용법은:

caddy <command> [<args...>]

<carets>는 여러분의 입력으로 대체되는 파라미터를 나타내요.

[brackets]는 선택적 파라미터를 나타내요. (brackets)는 필수 파라미터를 나타내요.

줄임표 ...는 연속, 즉 하나 이상의 파라미터를 나타내요.

--flags는 -f 같은 단일 문자 약어를 가질 수 있어요.

빠른 시작: caddy, caddy help, 또는 man caddy (설치된 경우)

caddy adapt 구성 문서를 네이티브 JSON으로 어댑트

caddy build-info 빌드 정보 출력

caddy completion 셸 완성 스크립트 생성

caddy environ 환경 출력

caddy file-server 간단하지만 프로덕션에 바로 쓸 수 있는 파일 서버

caddy file-server export-template 파일 서버의 기본 파일 브라우저 템플릿을 내보내는 보조 명령

caddy fmt Caddyfile 포맷

caddy hash-password 비밀번호를 해시하고 base64로 출력

caddy help caddy 명령에 대한 도움말 보기

caddy list-modules 설치된 Caddy 모듈 나열

caddy manpage manpage 생성

caddy reload 실행 중인 Caddy 프로세스의 구성을 변경

caddy respond 개발과 테스트를 위한 빠르고 깔끔한 하드코딩 HTTP 서버

caddy reverse-proxy 간단하지만 프로덕션에 바로 쓸 수 있는 HTTP(S) 리버스 프록시

caddy run 포그라운드에서 Caddy 프로세스 시작

caddy start 백그라운드에서 Caddy 프로세스 시작

caddy stop 실행 중인 Caddy 프로세스 중지

caddy storage export 구성된 스토리지의 내용을 tarball로 내보내기

caddy storage import 이전에 내보낸 tarball을 구성된 스토리지로 가져오기

caddy trust 로컬 신뢰 저장소에 인증서 설치

caddy untrust 로컬 신뢰 저장소에서 인증서 신뢰 해제

caddy upgrade Caddy를 최신 릴리스로 업그레이드

caddy add-package 추가 플러그인과 함께 Caddy를 최신 릴리스로 업그레이드

caddy remove-package 일부 플러그인을 제거한 채 Caddy를 최신 릴리스로 업그레이드

caddy validate 구성 파일이 유효한지 테스트

caddy version 버전 출력

신호 (Signals) Caddy가 신호를 처리하는 방식

종료 코드 (Exit codes) Caddy 프로세스가 종료할 때 발생

서브커맨드

`caddy adapt`

caddy adapt
	[-c, --config <path>]
	[-a, --adapter <name>]
	[-p, --pretty]
	[--validate]

구성을 Caddy의 네이티브 JSON 구성 구조로 어댑트하고 출력을 stdout에, 경고는 stderr에 기록한 다음 종료해요.

--config는 구성 파일의 경로예요. 생략하면 현재 디렉터리에 Caddyfile이 있으면 그걸 가정하고, 그렇지 않으면 이 플래그가 필수예요. 일반 파일 대신 stdin을 사용하려면 경로로 -를 사용하세요.

--adapter는 사용할 구성 어댑터를 지정해요. 기본은 caddyfile이에요.

--pretty는 사람이 읽기 쉽도록 들여쓰기로 출력을 포맷해요.

--validate는 어댑트된 구성을 로드하고 프로비저닝해 유효성을 확인해요(하지만 실제로 구성 실행을 시작하지는 않아요).

성공적으로 어댑트된 구성도 검증에 실패할 수 있다는 점을 주의하세요. 예를 들어 이 Caddyfile을 사용해보세요:

localhost

tls cert_notexist.pem key_notexist.pem

어댑트를 시도해보세요:

caddy adapt --config Caddyfile

오류 없이 성공해요. 그럼 시도해보세요:

caddy adapt --config Caddyfile --validate
adapt: validation: loading app modules: module name 'tls': provision tls: loading certificates: open cert_notexist.pem: no such file or directory

그 Caddyfile이 오류 없이 JSON으로 어댑트될 수 있어도 실제 인증서 및/또는 키 파일이 존재하지 않으므로, 그 오류가 프로비저닝 단계에서 발생해 검증이 실패해요. 따라서 검증은 어댑트보다 더 강력한 오류 검사예요.

예제

쉽게 읽고 수동으로 조정할 수 있도록 Caddyfile을 JSON으로 어댑트하려면:

caddy adapt --config /path/to/Caddyfile --pretty

`caddy build-info`

caddy build-info

Go가 제공하는 빌드 정보(메인 모듈 경로, 패키지 버전, 모듈 대체)를 출력해요.

`caddy completion`

caddy completion [bash|zsh|fish|powershell]

셸 완성 스크립트를 생성해요. 이렇게 하면 caddy 명령을 입력할 때 탭 완성이나 자동 완성(셸에 따라 유사)을 얻을 수 있어요.

이 스크립트를 특정 셸에 설치하는 지침을 얻으려면 caddy help completion 또는 caddy completion -h를 실행하세요.

`caddy environ`

caddy environ

caddy가 보는 환경을 출력하고 종료해요. systemd 같은 init 시스템이나 프로세스 관리자 유닛을 디버깅할 때 유용할 수 있어요.

`caddy file-server`

caddy file-server
	[-r, --root <path>]
	[--listen <addr>]
	[-d, --domain <example.com>]
	[-b, --browse]
	[--reveal-symlinks]
	[-t, --templates]
	[--access-log]
	[-v, --debug]
	[-f, --file-limit <number>]
	[--no-compress]
	[-p, --precompressed]

간단하지만 프로덕션에 바로 쓸 수 있는 정적 파일 서버를 띄워요.

--root는 루트 파일 경로를 지정해요. 기본은 현재 작업 디렉터리예요.

--listen은 리스너 주소를 받아요. 기본은 :80이며, --domain을 사용하면 :443이 기본이 돼요.

--domain은 그 호스트 이름으로만 파일을 서빙하며, Caddy가 HTTPS로 서빙하려 시도해요. 공개 도메인 이름이라면 먼저 공개 DNS가 올바르게 구성되어 있는지 확인하세요. 기본 포트는 443으로 바뀌어요.

--browse는 인덱스 파일이 없는 디렉터리가 요청되면 디렉터리 목록을 활성화해요.

--reveal-symlinks는 --browse가 활성화된 경우 디렉터리 목록에 심볼릭 링크의 대상을 보여줘요.

--templates는 템플릿 렌더링을 활성화해요.

--access-log는 요청/액세스 로그를 활성화해요.

--debug는 상세 로깅을 활성화해요.

--file-limit은 디렉터리 목록에 표시할 최대 파일 수를 설정해요. 기본: 10000. 파일 수가 이 한도를 초과하면 처음 N개 파일만 표시돼요. N은 지정된 한도예요.

--no-compress는 압축을 비활성화해요. 기본적으로 Zstandard와 Gzip 압축이 활성화되어 있어요.

--precompressed는 사전 압축된 사이드카 파일을 검색할 인코딩 형식을 지정해요. 여러 형식에 대해 반복할 수 있어요. 자세한 내용은 file_server 지시문을 참고하세요.

이 명령은 admin API를 비활성화해서 로컬 개발 머신에서 여러 인스턴스를 실행하기 더 쉽게 해요.

`caddy file-server export-template`

caddy file-server export-template

기본 파일 브라우징 템플릿을 stdout으로 내보내요

`caddy fmt`

caddy fmt [<path>]
	[-w, --overwrite]
	[-d, --diff]

Caddyfile을 포맷하거나 정리한 다음 종료해요. --overwrite를 사용하지 않으면 결과가 stdout으로 출력되고, 차이가 있으면 코드 1로 종료해요.

<path>는 Caddyfile의 경로를 지정해요. -라면 입력은 stdin에서 읽어요. 생략하면 현재 디렉터리의 Caddyfile 파일을 가정해요.

--overwrite는 결과를 터미널에 출력하는 대신 입력 파일에 쓰게 해요. 입력이 일반 파일이 아니면 이 플래그는 효과가 없어요.

--diff는 출력을 입력과 비교하게 하고, 다른 줄 앞에 -와 +를 붙여요. 변경되지 않은 줄은 정렬을 위해 두 칸이 붙고, 이것은 유효한 패치 형식이 아니며 시각적 도구로만 쓰기 위한 것임을 주의하세요.

`caddy hash-password`

caddy hash-password
	[-p, --plaintext <password>]
	[-a, --algorithm <name>]
	[--bcrypt-cost <cost>]
	[--argon2id-time <iterations>]
	[--argon2id-memory <KiB>]
	[--argon2id-threads <threads>]
	[--argon2id-keylen <bytes>]

일반 텍스트 비밀번호를 해시하는 편리한 방법이에요. 결과 해시는 Caddy 구성에서 직접 사용할 수 있는 형식으로 stdout에 기록돼요.

--plaintext는 해시할 비밀번호예요. 생략하면 stdin에서 읽어요. Caddy가 제어 TTY에 연결되어 있으면 입력이 반향되지 않아요.

--algorithm은 해시 알고리즘을 선택하며, argon2id(권장) 또는 bcrypt예요. 기본: bcrypt.

--bcrypt-cost는 bcrypt 비용을 설정해요. 4에서 31까지예요. 높을수록 해시 계산이 느려지므로 무차별 대입 공격에 더 강해져요. 생략하거나 범위를 벗어나면 기본 14가 사용돼요. bcrypt에서만 사용돼요.

다음 플래그는 argon2id에서만 사용돼요:

--argon2id-time은 수행할 반복 횟수예요. 높을수록 해시가 더 느려지고 무차별 대입 공격에 강해져요. 기본: 1.

--argon2id-memory는 사용할 메모리 양(KiB)이에요. 높을수록 GPU/ASIC 공격에 대한 저항이 높아져요. 기본: 47104 (46 MiB).

--argon2id-threads는 사용할 CPU 스레드 수예요. 기본: 1.

--argon2id-keylen은 결과 해시의 길이(바이트)예요. 기본: 32.

`caddy help`

caddy help [<command>]

CLI 도움말 텍스트를, 선택적으로 특정 서브커맨드에 대해 출력한 다음 종료해요.

`caddy list-modules`

caddy list-modules
	[--packages]
	[--versions]
	[-s, --skip-standard]
	[--json]

설치된 Caddy 모듈을, 선택적으로 관련 Go 모듈의 패키지 및/또는 버전 정보와 함께 출력한 다음 종료해요.

일부 스크립트 상황에서는 모든 표준 모듈까지 출력하는 것이 중복될 수 있어서, --skip-standard로 그 출력을 생략할 수 있어요.

--json은 모듈 정보를 JSON 형식으로 출력하며, 프로그래매틱 처리에 유용할 수 있어요.

참고: Go의 버그로 인해 버전 정보는 Caddy가 메인 모듈이 아니라 의존성으로 빌드될 때만 사용할 수 있어요. 이걸 더 쉽게 하려면 xcaddy를 사용하세요.

`caddy manpage`

caddy manpage
	(-o, --directory <path>)

Caddy 명령에 대한 매뉴얼/문서 페이지를 생성하고 지정된 경로의 디렉터리에 써요. 이 명령의 출력은 man 명령으로 읽을 수 있어요.

--directory (필수)는 man 페이지를 쓸 디렉터리 경로예요. 없으면 생성돼요.

생성 후 매뉴얼 페이지는 일반적으로 설치해야 해요. 절차는 플랫폼마다 다르지만 일반적인 Linux 시스템에서는 이렇게 해요:

**$ caddy manpage --directory man
$ gzip -r man/
$ sudo cp man/* /usr/share/man/man8/
$ sudo mandb
**

그럼 터미널에서 man caddy(또는 서브커맨드는 man caddy-*)를 실행해 문서를 읽을 수 있어요.

매뉴얼 페이지는 우리 웹사이트의 문서와는 별개의 문서예요. 우리 웹사이트는 자주 업데이트되는 더 포괄적인 문서를 갖고 있어요.

`caddy reload`

caddy reload
	[-c, --config <path>]
	[-a, --adapter <name>]
	[--address <interface>]
	[-f, --force]

실행 중인 Caddy 인스턴스에 새 구성을 줘요. 이는 문서를 /load 엔드포인트로 POST하는 것과 같은 효과지만, 이 명령은 구성 파일을 중심으로 한 간단한 워크플로우에 편리해요. stop, start, run 명령과 비교해 이 단일 명령만이 실행 중인 구성을 변경/리로드하는 올바른 의미론적 방법이에요.

이 명령은 API를 사용하므로 admin 엔드포인트가 비활성화되어 있으면 안 돼요.

--config는 적용할 구성 파일이에요. -라면 구성은 stdin에서 읽어요. 지정하지 않으면 현재 작업 디렉터리의 Caddyfile 파일을 시도하고, 있으면 caddyfile 구성 어댑터로 어댑트해요. 그렇지 않으면 로드할 구성 파일이 없다면 오류예요.

--adapter는 사용할 구성 어댑터를 지정해요(있을 경우). --config 파일 이름이 Caddyfile로 시작하거나 .caddyfile로 끝나면 caddyfile 어댑터를 가정하므로 이 플래그는 필요 없어요. 그렇지 않으면 제공된 구성 파일이 Caddy의 네이티브 JSON 형식이 아닐 때 이 플래그가 필수예요.

--address는 admin 엔드포인트가 기본 주소에서 수신 대기하지 않고 제공된 구성 파일의 주소와 다를 때 사용해야 해요.

--force는 지정된 구성이 Caddy가 이미 실행 중인 것과 같아도 리로드가 일어나게 해요. Caddy가 모듈을 재프로비저닝하도록 강제하는 데 유용할 수 있으며, 이는 부작용이 있을 수 있어요. 예를 들어 수동으로 로드된 TLS 인증서를 다시 로드하는 것처럼요.

`caddy respond`

caddy respond
	[-s, --status <code>]
	[-H, --header "<Field>: <value>"]
	[-b, --body <content>]
	[-l, --listen <addr>]
	[-v, --debug]
	[--access-log]
	[<status|body>]

개발, 스테이징, 일부 프로덕션 사용 사례에 유용한 하나 이상의 간단한 하드코딩 HTTP 서버를 시작해요. HTTP 클라이언트, 스크립트, 심지어 로드 밸런서를 검증하거나 디버깅하는 데 유용할 수 있어요.

--status는 반환할 HTTP 상태 코드예요.

--header는 HTTP 헤더를 추가해요. Field: value 형식이 기대돼요. 이 플래그는 여러 번 사용할 수 있어요.

--body는 응답 본문을 지정해요. 대안으로 본문을 stdin에서 파이프할 수 있어요.

--listen은 리스너 주소이며, Caddy가 인식하는 모든 네트워크 주소가 될 수 있고, 여러 서버를 시작하기 위해 포트 범위를 포함할 수 있어요.

--debug는 상세 디버그 로깅을 활성화해요.

--access-log는 액세스/요청 로깅을 활성화해요.

옵션 없이 실행하면 이 명령은 무작위의 사용 가능한 포트에서 수신 대기하고 빈 200 응답으로 HTTP 요청에 응답해요. 리스너 주소는 --listen 플래그로 커스터마이즈할 수 있으며 항상 stdout에 출력돼요. 리스너 주소가 포트 범위를 포함하면 여러 서버가 시작돼요.

마지막의 이름 없는 인수가 주어지면, 3자리 숫자라면 상태 코드(--status 플래그와 같음)로 처리돼요. 그렇지 않으면 응답 본문(--body 플래그와 같음)으로 사용돼요. --status와 --body 플래그는 항상 이 인수를 덮어써요.

본문은 3가지 방법으로 줄 수 있어요: 플래그, 명령의 마지막 (이름 없는) 인수, 또는 stdin 파이프(플래그와 인수가 설정되지 않은 경우). 본문에는 제한된 템플릿 평가가 지원되며 다음 변수를 사용해요:

Variable	Description
`.N`	서버 번호
`.Port`	리스너 포트
`.Address`	리스너 주소

예제

무작위 포트에서 빈 200 응답:

caddy respond

본문이 있는 HTTP 응답:

caddy respond "Hello, world!"

여러 서버와 템플릿:

**$ caddy respond --listen :2000-2004 "I'm server {{.N}} on port {{.Port}}"**

Server address: [::]:2000
Server address: [::]:2001
Server address: [::]:2002
Server address: [::]:2003
Server address: [::]:2004

**$ curl 127.0.0.1:2002**
I'm server 2 on port 2002

유지보수 페이지 파이프:

cat maintenance.html | caddy respond \
	--listen :80 \
	--status 503 \
	--header "Content-Type: text/html"

`caddy reverse-proxy`

caddy reverse-proxy
	[-f, --from <addr>]
	(-t, --to <addr>)
	[-H, --header-up "<Field>: <value>"]
	[-d, --header-down "<Field>: <value>"]
	[-c, --change-host-header]
	[-r, --disable-redirects]
	[-i, --internal-certs]
	[-v, --debug]
	[--access-log]
	[--insecure]

간단하지만 프로덕션에 바로 쓸 수 있는 리버스 프록시예요. 빠른 배포, 데모, 개발에 유용해요.

단순히 HTTP(S) 트래픽을 --from 주소에서 --to 주소로 전달해요. --to 주소는 플래그를 반복해 여러 개 지정할 수 있어요. --to 주소가 적어도 하나는 필요해요. --to 주소는 여러 업스트림으로 확장되는 지름길로 포트 범위를 가질 수 있어요.

주소에 달리 지정되지 않으면 호스트 이름이 주어진 경우 --from 주소는 HTTPS로 간주되고 --to 주소는 HTTP로 간주돼요.

--from 주소에 호스트나 IP가 있으면 Caddy는 인증서로 HTTPS로 프록시를 서빙하려 시도해요(HTTP 스킴이나 포트로 덮어쓰지 않는 한).

HTTPS를 서빙할 경우:

--disable-redirects는 HTTP 포트에 바인딩하지 않도록 사용할 수 있어요.

--internal-certs는 공개 인증서 발급을 시도하는 대신 내부 CA로 인증서 발급을 강제하는 데 사용할 수 있어요.

프록시할 경우:

--header-up은 업스트림으로 보낼 요청 헤더를 설정하는 데 사용할 수 있어요.

--header-down은 클라이언트로 돌려보낼 응답 헤더를 설정하는 데 사용할 수 있어요.

--change-host-header는 들어오는 Host 헤더를 기본값으로 사용하는 대신 요청의 Host 헤더를 업스트림 주소로 설정해요.

이는 --header-up "Host: {http.reverse_proxy.upstream.hostport}"의 지름길이에요.

--insecure는 업스트림과의 TLS 검증을 비활성화해요. 경고: 이는 업스트림의 인증서를 검증하지 않음으로써 보안을 비활성화해요.

--debug는 상세 로깅을 활성화해요.

이 명령은 admin API를 비활성화해 로컬 개발 머신에서 여러 인스턴스를 실행하기 더 쉽게 해요.

`caddy run`

caddy run
	[-c, --config <path>]
	[-a, --adapter <name>]
	[--pidfile <file>]
	[-e, --environ]
	[--envfile <file>]
	[-r, --resume]
	[-w, --watch]

Caddy를 실행하고 무기한 블로킹해요. 즉 "데몬" 모드예요.

--config는 즉시 로드하고 사용할 초기 구성 파일을 지정해요. -라면 구성은 stdin에서 읽어요. 구성이 지정되지 않으면 Caddy는 빈 구성으로 실행되고 admin API 엔드포인트에 기본 설정을 사용하며, 이를 사용해 새 구성을 공급할 수 있어요. 특수한 경우로, 현재 작업 디렉터리에 "Caddyfile"이라는 파일이 있고 caddyfile 구성 어댑터가 연결되어 있으면(기본), 명령줄 플래그 없이도 그 파일이 로드되어 Caddy를 구성하는 데 사용돼요.

--adapter는 초기 구성을 로드할 때 사용할 구성 어댑터의 이름이에요(있는 경우). --config 파일 이름이 Caddyfile로 시작하거나 .caddyfile로 끝나면 caddyfile 어댑터를 가정하므로 이 플래그는 필요 없어요. 그렇지 않으면 제공된 구성 파일이 Caddy의 네이티브 JSON 형식이 아닐 때 이 플래그가 필수예요. 경고는 로그에 출력되지만, 오류 없이 어댑트된 것이라면 경고가 있어도 즉시 사용된다는 점을 주의하세요. 어댑트 결과를 먼저 검토하려면 caddy adapt 서브커맨드를 사용하세요.

--pidfile은 PID를 지정된 파일에 써요.

--environ은 시작 전에 환경을 출력해요. caddy environ 명령과 같지만 출력 후 종료하지 않아요.

--envfile은 KEY=VALUE 형식으로 지정된 파일에서 환경 변수를 로드해요. #로 시작하는 주석이 지원되고, 키는 export 접두사가 붙을 수 있으며, 값은 큰따옴표로 묶을 수 있고(안의 큰따옴표는 이스케이프 가능), 여러 줄 값이 지원돼요.

--resume은 자동 저장된 마지막으로 로드된 구성을 사용하며, --config 플래그(있을 경우)를 덮어써요. 이 플래그를 사용하면 머신 재부팅이나 프로세스 재시작에도 구성 내구성이 보장돼요. API 중심 배포에서 가장 유용해요.

--watch는 구성 파일을 감시하고 변경 후 자동으로 다시 로드해요. ⚠️ 이 기능은 로컬 개발 환경에서만 사용하기 위한 것이에요!

프로덕션에서 실행하는 동안 구성을 변경하려고 서버를 멈추지 마세요! 그렇게 하면 다운타임이 발생해요. (이건 당연해 보이지만 그에 대한 불만을 얼마나 많이 받는지 놀랄 거예요.) 대신 caddy reload 명령을 사용하거나 프로세스에 SIGUSR1 신호를 보내세요. 이는 현재 로드된 구성으로 caddy reload를 실행하는 것과 같은 효과예요.

`caddy start`

caddy start
	[-c, --config <path>]
	[-a, --adapter <name>]
	[--envfile <file>]
	[--pidfile <file>]
	[-w, --watch]

caddy run과 같지만 백그라운드로 실행돼요. 이 명령은 백그라운드 프로세스가 성공적으로 실행될 때까지(또는 실행 실패까지) 블로킹한 다음 반환해요.

참고: --config 플래그는 stdin에서 구성을 읽는 -를 지원하지 않아요.

이 명령은 시스템 서비스나 Windows에서 사용하는 것이 권장되지 않아요. Windows에서는 자식 프로세스가 터미널에 계속 붙어 있어 창을 닫으면 Caddy가 강제로 중지되는데, 이는 명확하지 않아요. 대신 Caddy를 서비스로 실행하는 것을 고려해보세요.

시작되면 caddy stop 또는 POST /stop API 엔드포인트로 백그라운드 프로세스를 종료할 수 있어요.

`caddy stop`

caddy stop
	[--address <interface>]
	[-c, --config <path> [-a, --adapter <name>]]

서버를 중지(및 재시작)하는 것은 구성 변경과 직교해요. 다운타임을 원하지 않으면 프로덕션에서 구성을 변경하기 위해 stop 명령을 사용하지 마세요. 대신 caddy reload 명령을 사용하세요.

실행 중인 Caddy 프로세스(stop 명령의 프로세스 제외)를 정상적으로 중지하고 종료하게 해요. 정상 종료를 위해 admin API의 POST /stop 엔드포인트를 사용해요.

이 요청의 주소는 실행 중인 인스턴스의 admin API가 기본 리스너 주소를 사용하지 않는다면 --address 플래그나 주어진 --config로 커스터마이즈할 수 있어요.

현재 구성을 중지하고 싶지만 프로세스를 종료하고 싶지 않다면, 빈 구성으로 caddy reload를 사용하거나 DELETE /config/ 엔드포인트를 사용하세요.

`caddy storage`

⚠️ 실험적 기능

Caddy의 구성된 데이터 스토리지의 내용을 내보내고 가져올 수 있게 해줘요.

이전 스토리지 모듈에서 새 것으로 전환할 때, 이전 것에서 내보내고 구성을 업데이트한 다음 새 것에 가져오는 방식으로 유용해요.

다음 명령은 내보내기 명령의 출력을 가져오기 명령으로 파이프해, 이전 및 새 구성을 사용해 서로 다른 모듈 간에 스토리지를 한 번에 복사할 수 있어요.

$ caddy storage export -c Caddyfile.old -o- |
  caddy storage import -c Caddyfile.new -i-

파일시스템 스토리지를 사용할 때는 Caddy가 일반적으로 실행하는 사용자와 같은 사용자로 내보내기 명령을 실행해야 합니다. 그렇지 않으면 잘못된 스토리지 위치가 사용될 수 있어요.

예를 들어 Caddy를 systemd 서비스로 실행하면 caddy 사용자로 실행되므로 내보내기나 가져오기 명령을 그 사용자로 실행해야 해요. 이는 보통 sudo -u caddy <command>로 할 수 있어요.

`caddy storage export`

caddy storage export
	-c, --config <path>
	[-o, --output <path>]

--config는 로드할 구성 파일이에요. 올바른 스토리지 모듈에 연결하기 위해 필수예요.

--output은 tarball을 쓸 파일 이름이에요. -라면 출력은 stdout으로 기록돼요.

`caddy storage import`

caddy storage import
	-c, --config <path>
	-i, --input <path>

--config는 로드할 구성 파일이에요. 올바른 스토리지 모듈에 연결하기 위해 필수예요.

--input은 읽을 tarball의 파일 이름이에요. -라면 입력은 stdin에서 읽혀요.

`caddy trust`

caddy trust
	[--ca <id>]
	[--address <interface>]
	[-c, --config <path> [-a, --adapter <name>]]

Caddy의 PKI 앱이 관리하는 CA의 루트 인증서를 로컬 신뢰 저장소에 설치해요.

Caddy는 루트 인증서가 처음 생성될 때 자동으로 로컬 신뢰 저장소에 설치하려 시도하지만, Caddy가 신뢰 저장소에 쓸 적절한 권한이 없으면 실패할 수 있어요. 이 명령은 서버 프로세스가 권한 없는 사용자(systemd 등)로 실행될 때 사용 전에 인증서를 미리 설치하는 데 필요해요. unix 시스템에서는 이 명령을 sudo로 실행해야 할 수 있어요.

기본적으로 이 명령은 Caddy의 기본 CA(즉 "local")에 대한 루트 인증서를 설치해요. --ca 플래그로 다른 CA의 ID를 지정할 수 있어요.

이 명령은 Caddy의 admin API에 연결해 GET /pki/ca/<id>/certificates 엔드포인트로 루트 인증서를 가져오려 시도해요. 실행 중인 인스턴스의 admin API가 기본 리스너 주소를 사용하지 않는다면 --address를 명시적으로 지정하거나 --config 플래그로 구성에서 admin 주소를 로드할 수 있어요.

admin API를 다른 머신에서 접근할 수 있게 만든 경우 이 명령으로 caddy 바이너리를 사용해 네트워크의 다른 머신에 인증서를 설치할 수도 있어요 - 이렇게 할 때는 admin API를 신뢰할 수 없는 클라이언트에 노출하지 않도록 주의하세요.

`caddy untrust`

caddy untrust
	[-p, --cert <path>]
	[--ca <id>]
	[--address <interface>]
	[-c, --config <path> [-a, --adapter <name>]]

로컬 신뢰 저장소에서 루트 인증서의 신뢰를 해제해요.

이 명령은 신뢰를 제거할 뿐, 루트 인증서를 신뢰 저장소에서 완전히 삭제하지는 않을 수 있어요. 따라서 새 인증서를 반복적으로 신뢰하고 신뢰 해제하면 신뢰 데이터베이스가 가득 찰 수 있어요.

이 명령은 Caddy의 구성된 스토리지에서 인증서 파일을 삭제하거나 수정하지 않아요.

이 명령은 두 가지 방법 중 하나로 사용할 수 있어요:

--cert 플래그로 신뢰 해제할 루트 인증서의 직접 경로를 지정.
GET /pki/ca/<id>/certificates 엔드포인트를 사용해 admin API에서 루트 인증서를 가져오기. 플래그가 없으면 기본 동작이에요.

admin API를 사용하면 CA ID는 기본적으로 "local"로 설정돼요. --ca 플래그로 다른 CA의 ID를 지정할 수 있어요. 실행 중인 인스턴스의 admin API가 기본 리스너 주소를 사용하지 않는다면 --address를 명시적으로 지정하거나 --config 플래그로 구성에서 admin 주소를 로드할 수 있어요.

`caddy upgrade`

⚠️ 실험적 기능

caddy upgrade
	[-k, --keep-backup]

현재 Caddy 바이너리를 다운로드 페이지의 최신 버전으로, Caddy 웹사이트에 등록된 모든 3rd-party 플러그인을 포함해 같은 모듈이 설치된 채로 교체해요.

업그레이드는 실행 중인 서버를 중단하지 않아요. 현재는 명령이 디스크의 바이너리만 교체해요. 좋은 방법을 찾을 수 있다면 미래에 바뀔 수 있어요.

업그레이드 프로세스는 장애 허용적이에요. 현재 바이너리는 먼저 백업되고(현재 것 옆에 복사) 문제가 생기면 자동으로 복원돼요. 업그레이드 프로세스 완료 후 백업을 유지하고 싶다면 --keep-backup 옵션을 사용할 수 있어요.

이 명령은 사용자에게 실행 파일에 쓸 권한이 없으면 상승된 권한이 필요할 수 있어요.

`caddy add-package`

⚠️ 실험적 기능

caddy add-package <packages...>
	[-k, --keep-backup]

caddy upgrade와 유사하게 현재 Caddy 바이너리를 같은 모듈이 설치된 최신 버전으로 교체하되, 인수로 나열된 패키지가 새 바이너리에 추가로 포함돼요. 설치할 수 있는 패키지 목록은 다운로드 페이지에서 찾을 수 있어요. 각 인수는 전체 패키지 이름이어야 하며, 선택적으로 @와 버전을 붙여(예: github.com/caddy-dns/[email protected]) 특정 버전을 설치할 수 있어요.

예:

caddy add-package github.com/caddy-dns/cloudflare

`caddy remove-package`

⚠️ 실험적 기능

caddy remove-package <packages...>
	[-k, --keep-backup]

caddy upgrade와 유사하게 현재 Caddy 바이너리를 같은 모듈이 설치된 최신 버전으로 교체하되, 인수로 나열된 패키지가 현재 바이너리에 없었다면 그것들을 제외해요. 현재 바이너리에 포함된 비표준 모듈의 패키지 이름 목록을 보려면 caddy list-modules --packages를 실행하세요.

`caddy validate`

caddy validate
	[-c, --config <path>]
	[-a, --adapter <name>]
	[--envfile <file>]

구성 파일을 검증한 다음 종료해요. 이 명령은 구성을 역직렬화한 다음 모든 모듈을 구성을 시작하듯 로드하고 프로비저닝하지만, 실제로 구성을 시작하지는 않아요. 이는 로딩이나 프로비저닝 단계에서 발생하는 구성 오류를 드러내며, 구성을 JSON으로 직렬화하는 것보다 더 강력한 오류 검사예요.

모듈이 실제로 프로비저닝되므로 이 명령은 Caddy를 시작하기 전에 실행하는 것이 가장 좋아요. 일부 모듈은 프로비저닝 중에 배타적 리소스를 획득하며, 두 번째 Caddy 프로세스는 실행 중인 인스턴스가 보유하는 동안 그것을 획득할 수 없어요. 예를 들어 acme_server 지시문은 한 번에 한 프로세스만 열 수 있는 데이터베이스를 여는데, 그래서 Caddy가 이미 실행 중일 때 그것을 사용하는 구성을 검증하면 구성 자체는 정상이어도 데이터베이스 타임아웃으로 실패해요. 실행 중인 인스턴스에 대해 구성을 확인하려면 대신 caddy reload를 사용하세요. 실행 중인 프로세스 내에서 새 구성을 프로비저닝하므로 그 리소스에 대해 실행 중인 인스턴스와 경합하지 않아요. 프로비저닝이 실패하면 활성 구성이 계속 실행되고, 성공하면 새 구성이 적용돼요.

--config는 검증할 구성 파일이에요. -라면 구성은 stdin에서 읽어요. 기본은 현재 디렉터리의 Caddyfile(있는 경우)이에요.

--adapter는 사용할 구성 어댑터의 이름이에요. --config 파일 이름이 Caddyfile로 시작하거나 .caddyfile로 끝나면 caddyfile 어댑터를 가정하므로 이 플래그는 필요 없어요. 그렇지 않으면 제공된 구성 파일이 Caddy의 네이티브 JSON 형식이 아닐 때 이 플래그가 필수예요.

`caddy version`

caddy version

버전을 출력하고 종료해요.

신호 (Signals)

Caddy는 특정 신호를 잡고 다른 신호는 무시해요. 신호는 특정 프로세스 동작을 시작할 수 있어요.

Signal	Behavior
`SIGINT`	정상 종료. 신호를 다시 보내면 즉시 강제 종료.
`SIGQUIT`	Caddy를 즉시 종료하지만, 중요하므로 스토리지의 잠금은 정리해요.
`SIGTERM`	정상 종료.
`SIGUSR1`	구성 파일을 다시 로드하지만, `caddy run`으로 시작했고(without `--resume`) API(`caddy reload` 포함)로 구성 변경이 없었을 때만.
`SIGUSR2`	무시됨.
`SIGHUP`	무시됨.

정상 종료는 새 연결을 더 이상 수락하지 않고, 기존 연결은 소켓이 닫히기 전에 드레인(drain)된다는 것을 의미해요. 유예 기간이 적용될 수 있고(구성 가능), 유예 기간이 끝나면 연결이 강제로 종료돼요. 스토리지의 잠금과 개별 모듈이 해제해야 하는 다른 리소스는 정상 종료 중에 정리돼요.

구성 리로드 신호(SIGUSR1)를 받으면 강제 구성 리로드(즉 구성 텍스트가 변경되지 않아도 어쨌든 리로드)처럼 동작하며, 이는 TLS 인증서 같은 의존 파일을 디스크에서 다시 로드할 수 있어요.

신호 기반 구성 리로드는 Caddy가 구성 파일로 caddy run으로 시작된 경우에만 활성화돼요. --resume으로 시작하면(API 워크플로우를 의미하므로), admin API로 구성 변경을 받으면, 또는 원래 시작했을 때와 다른 파일 이름이나 구성 어댑터로 caddy reload를 실행하면 비활성화(로그 경고와 함께 신호 무시)돼요. 이는 리로드 방법 간의 충돌을 피하기 위해서예요.

종료 코드 (Exit codes)

Caddy는 프로세스가 종료할 때 코드를 반환해요:

Code	Meaning
`0`	정상 종료.
`1`	시작 실패. 프로세스를 자동으로 재시작하지 마세요. 변경을 하지 않으면 다시 오류가 날 가능성이 높아요.
`2`	강제 종료. Caddy가 리소스를 정리하지 않고 종료하도록 강제됨.
`3`	종료 실패. Caddy가 정리 중 일부 오류와 함께 종료됨.

bash에서 echo $?로 마지막 명령의 종료 코드를 얻을 수 있어요.

더 알아보기 (Learn more)

Caddy 공식 문서