{{tag>[cli acme-sh acme config tls certificate dns]}} ====== acme.sh Configuration ====== ''acme.sh'' configuration은 account 공통 상태, domain별 발급 상태, certificate deployment 경로, DNS provider credential로 나뉜다. 이 file들은 private key나 API credential을 포함할 수 있으므로 wiki나 Git에 복사하지 않는다. ===== Summary ===== * 기본 configuration home은 ''~/.acme.sh/''이며 실행 user마다 분리된다. * 발급과 ''--install-cert'' command가 renewal에 필요한 값을 저장하므로 managed domain configuration을 임의로 편집하지 않는다. * DNS API credential 이름과 저장 동작은 provider hook마다 다르다. * 변경 후 ''--info'', ''--list'', staging issuance와 cron log로 검증한다. ===== Locations ===== ^ Scope ^ Default ^ Purpose ^ | program home | ''~/.acme.sh/'' | script, hook, internal data | | account | ''~/.acme.sh/account.conf'' | CA account와 공통 setting | | certificate | ''~/.acme.sh/DOMAIN/'' | domain key, certificate, managed renewal state | | log | ''~/.acme.sh/acme.sh.log'' | ''--log''를 사용한 실행 기록 | ECC와 RSA certificate를 함께 관리하거나 custom home을 사용하면 실제 directory 이름이 달라질 수 있다. path를 추측하지 말고 다음 command로 현재 상태를 확인한다. acme.sh --info acme.sh --info -d example.com acme.sh --list ===== Storage Options ===== * ''**--home** DIRECTORY'': acme.sh program home을 지정한다. * ''**--config-home** DIRECTORY'': account와 domain configuration 저장소를 지정한다. * ''**--cert-home** DIRECTORY'': managed certificate 저장소를 지정한다. * ''**--accountconf** FILE'': custom account configuration file을 지정한다. * ''**--log** [FILE]'': log를 활성화하고 선택적으로 path를 지정한다. * ''**--log-level** 1|2'': log verbosity를 지정한다. scheduled renewal은 interactive shell의 alias나 현재 directory에 의존하지 않도록 동일한 home을 명시한다. 0 0 * * * "/home/user/.acme.sh/acme.sh" --cron --home "/home/user/.acme.sh" > /dev/null ===== Authoring Workflow ===== managed configuration의 내부 variable 이름을 직접 수정하는 대신 public command option으로 상태를 만든다. # account 연락처 변경 acme.sh --update-account --server letsencrypt -m you@example.com # 기본 CA 저장 acme.sh --set-default-ca --server letsencrypt # domain validation과 issuance setting 저장 acme.sh --issue -d example.com -w /var/www/html # deployment path와 reload command 저장 acme.sh --install-cert -d example.com \ --key-file /etc/nginx/tls/example.com.key \ --fullchain-file /etc/nginx/tls/example.com.crt \ --reloadcmd "nginx -t && systemctl reload nginx" command line option은 현재 실행에 적용되고, 발급·설치·account command가 renewal에 필요한 값을 managed configuration에 기록한다. version이나 provider hook에 따라 내부 key가 바뀔 수 있으므로 ''account.conf''와 domain ''.conf''의 내부 이름을 automation interface로 사용하지 않는다. ===== DNS Credentials ===== DNS provider hook이 요구하는 environment variable을 현재 shell에 주입한 뒤 최초 issuance를 실행한다. 아래 이름은 Cloudflare token 방식의 redacted example이며 실제 값은 secret manager에서 읽는다. export CF_Token='REDACTED' export CF_Account_ID='REDACTED' acme.sh --issue --dns dns_cf -d example.com -d '*.example.com' 실제 token을 shell script, command history, wiki, Git, process argument에 literal로 남기지 않는다. token에는 필요한 zone의 DNS record edit/read처럼 최소 권한만 부여한다. provider마다 variable 이름, token scope, account/zone ID 요구가 다르므로 공식 ''dnsapi'' 문서를 확인한다. acme.sh가 renewal을 위해 credential을 configuration에 저장할 수 있으므로 file 접근 권한과 backup 범위를 점검한다. chmod 700 ~/.acme.sh chmod 600 ~/.acme.sh/account.conf ===== Certificate Deployment ===== internal certificate path를 web server configuration에 직접 넣지 않는다. 운영용 destination을 먼저 만들고 owner와 mode를 정한 뒤 ''--install-cert''가 그 file을 갱신하게 한다. 아래 예시는 acme.sh를 root account에 설치해 root cron으로 갱신하는 server를 가정한다. 일반 user 설치에서는 destination write와 service reload에 필요한 최소 권한만 별도로 부여한다. sudo -i install -d -m 0750 /etc/nginx/tls touch /etc/nginx/tls/example.com.key /etc/nginx/tls/example.com.crt /root/.acme.sh/acme.sh --install-cert -d example.com \ --key-file /etc/nginx/tls/example.com.key \ --fullchain-file /etc/nginx/tls/example.com.crt \ --reloadcmd "nginx -t && systemctl reload nginx" exit ===== Precedence and Separation ===== * 실행 user가 달라지면 ''HOME'', account, cron, certificate inventory도 달라진다. issuance와 renewal은 같은 service account와 home을 사용한다. * custom ''--config-home''을 사용하면 cron과 manual command 양쪽에 같은 option을 적용한다. * domain별 validation과 deployment state는 공통 account setting과 분리해 관리한다. * CLI로 명시한 현재 실행 option과 저장된 renewal state가 충돌하면 ''--info -d DOMAIN''으로 effective domain 정보를 확인하고 정상 command로 다시 저장한다. ===== Validation ===== acme.sh --version acme.sh --info acme.sh --info -d example.com acme.sh --list # 현재 설정한 CA의 staging endpoint에서 새 test domain 흐름 검증 acme.sh --issue --test -d test.example.com -w /var/www/html # scheduled renewal check와 동일한 home 사용 acme.sh --cron --home ~/.acme.sh staging certificate는 browser가 신뢰하지 않으며 운영 배포용이 아니다. test domain, DNS, webroot가 실제로 준비된 경우에만 staging issuance를 실행한다. ===== Troubleshooting ===== * cron에서는 되지 않는 경우: interactive shell에만 있는 environment variable, ''PATH'', alias에 의존하는지 확인하고 executable과 ''--home''을 절대 경로로 지정한다. * 다른 certificate inventory가 보이는 경우: command를 실행한 user, ''HOME'', ''--config-home'', ECC/RSA 구분을 확인한다. * DNS renewal이 실패하는 경우: provider token 만료·scope·저장 여부와 hook의 최신 공식 variable 이름을 확인한다. * 갱신 후 service reload가 실패하는 경우: 저장된 ''--reloadcmd'', destination permission, config test command를 확인한다. * debug output 공유가 필요한 경우: secret을 redaction하고 ''--output-insecure''는 사용하지 않는다. ===== Compatibility ===== * configuration의 내부 key와 directory layout은 안정적인 public API가 아니다. backup은 필요하지만 직접 parsing하는 automation은 피한다. * DNS hook 동작과 credential schema는 provider API 및 acme.sh version에 따라 바뀔 수 있다. * system cron 대신 다른 scheduler를 사용해도 같은 user, home, environment, file permission을 재현해야 한다. ===== See Also ===== * [[acme-sh:ko]] * [[certbot:acme:ko]] * [[nginx:config:https]] * [[https://github.com/acmesh-official/acme.sh/wiki/dnsapi|acme.sh DNS API documentation]] * [[https://github.com/acmesh-official/acme.sh/wiki/How-to-install|acme.sh installation documentation]] ===== History ===== * codex:: 2026-07-19 Added acme.sh configuration storage, DNS credential, deployment, permission, and validation guidance. {{indexmenu>.#1|js}}