acme.sh Configuration

acme.sh configuration은 account 공통 상태, domain별 발급 상태, certificate deployment 경로, DNS provider credential로 나뉜다. 이 file들은 private key나 API credential을 포함할 수 있으므로 wiki나 Git에 복사하지 않는다.

• 기본 configuration home은 ~/.acme.sh/이며 실행 user마다 분리된다.
• 발급과 –install-cert command가 renewal에 필요한 값을 저장하므로 managed domain configuration을 임의로 편집하지 않는다.
• DNS API credential 이름과 저장 동작은 provider hook마다 다르다.
• 변경 후 –info, –list, staging issuance와 cron log로 검증한다.

ECC와 RSA certificate를 함께 관리하거나 custom home을 사용하면 실제 directory 이름이 달라질 수 있다. path를 추측하지 말고 다음 command로 현재 상태를 확인한다.

acme.sh --info
acme.sh --info -d example.com
acme.sh --list

• –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

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 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'

acme.sh가 renewal을 위해 credential을 configuration에 저장할 수 있으므로 file 접근 권한과 backup 범위를 점검한다.

chmod 700 ~/.acme.sh
chmod 600 ~/.acme.sh/account.conf

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

• 실행 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로 다시 저장한다.

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

• 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는 사용하지 않는다.

• 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을 재현해야 한다.

• acme-sh
• acme
• https
• acme.sh DNS API documentation
• acme.sh installation documentation

• codex:: 2026-07-19 Added acme.sh configuration storage, DNS credential, deployment, permission, and validation guidance.