acme.sh

acme.sh는 POSIX shell로 작성된 ACME client다. certificate 발급, 자동 갱신, server 배포, DNS API validation을 하나의 script로 처리하며 기본 설치는 user의 ~/.acme.sh/ 아래에 command와 상태를 저장한다.

• webroot, standalone, TLS-ALPN, Apache, Nginx, DNS API validation을 지원한다.
• 기본 certificate key type은 ECC이며 현재 upstream의 기본 CA는 ZeroSSL이다.
• installer는 기본적으로 shell alias와 daily cron job을 만든다.
• ~/.acme.sh/DOMAIN/의 내부 certificate file을 server에서 직접 참조하지 말고 –install-cert로 운영 경로에 복사한다.

공식 upstream은 Linux distribution별 APT/DNF package나 macOS Homebrew formula 대신 동일한 online installer와 Git 설치를 안내한다. Debian/Ubuntu, RHEL/Fedora, macOS에서는 curl 또는 wget, openssl, cron을 사용할 수 있는 shell 환경을 준비한다.

사용자가 제공한 공식 설치 예시다. [email protected]을 실제 ACME account 연락처로 바꾼다.

curl https://get.acme.sh | sh -s email=you@example.com

curl -fsSL https://get.acme.sh -o /tmp/get-acme.sh
less /tmp/get-acme.sh
sh /tmp/get-acme.sh email=you@example.com

설치 후 새 terminal을 열거나 profile을 다시 읽고 version을 확인한다. alias가 아직 적용되지 않았다면 절대 경로를 사용한다.

~/.acme.sh/acme.sh --version
acme.sh --version

git clone https://github.com/acmesh-official/acme.sh.git
cd acme.sh
./acme.sh --install -m you@example.com

upstream은 curl, openssl, crontab이 포함된 Cygwin 환경을 시험 대상으로 명시한다. 공식 winget package 설치 방법은 제공하지 않으므로 임의의 package ID를 사용하지 않는다.

acme.sh --issue -d example.com -w /var/www/html
~/.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"
acme.sh --list

• acme.sh –issue [validation options…] -d DOMAIN…: domain validation 후 certificate를 발급한다.
• acme.sh –install-cert [file options…] -d DOMAIN: 발급한 certificate와 key를 운영 경로에 복사하고 reload command를 저장한다.
• acme.sh –renew [–ecc] [–force] -d DOMAIN: 단일 certificate의 갱신 여부를 확인한다.
• acme.sh –cron [–home DIRECTORY]: 관리 중인 certificate의 scheduled renewal을 실행한다.
• acme.sh –list: 관리 중인 certificate를 표시한다.

• -d, –domain DOMAIN: certificate에 포함할 domain을 지정한다. SAN certificate에는 여러 번 사용한다.
• -w, –webroot DIRECTORY: HTTP-01 challenge file을 둘 webroot를 지정한다.
• –standalone: built-in server로 HTTP-01 validation을 수행한다. 외부에서 TCP/80에 접근할 수 있어야 한다.
• –alpn: built-in server로 TLS-ALPN validation을 수행한다. 외부에서 TCP/443에 접근할 수 있어야 한다.
• –dns DNS_HOOK: DNS API hook을 사용한다. hook을 생략한 manual mode는 자동 갱신에 적합하지 않다.
• –staging, –test: 지원되는 CA의 staging server를 사용해 발급 흐름을 시험한다.
• -k, –keylength BITS: ec-256, ec-384, 2048, 3072, 4096 등의 domain key type과 길이를 지정한다.
• –server SERVER: ACME directory URL 또는 알려진 CA alias를 선택한다.
• –cert-file, –key-file, –ca-file, –fullchain-file FILE: –install-cert가 갱신 때마다 복사할 destination을 지정한다.
• –reloadcmd COMMAND: 발급 또는 갱신 뒤 service가 새 certificate를 읽도록 실행할 command를 저장한다.
• –home, –config-home, –cert-home DIRECTORY: program, configuration, certificate 저장 위치를 분리 지정한다.

기본 CA를 Let's Encrypt로 바꾸려면 다음과 같이 명시한다.

acme.sh --set-default-ca --server letsencrypt

# staging에서 validation 경로 시험
acme.sh --issue --test -d example.com -w /var/www/html
 
# production certificate 발급
acme.sh --issue -d example.com -d www.example.com -w /var/www/html

acme.sh --issue --standalone -d example.com

# provider별 credential은 현재 shell 또는 제한된 secret file에서 주입한다.
# 실제 token을 command history나 wiki에 기록하지 않는다.
acme.sh --issue --dns dns_cf -d example.com -d '*.example.com'

provider별 variable 이름과 최소 권한은 반드시 공식 DNS API 문서에서 확인한다.

아래 예시는 acme.sh를 root account에 설치해 root cron으로 갱신하는 server를 가정한다. 일반 user로 설치했다면 해당 user에게 쓸 수 있는 destination과 password 입력 없이 실행 가능한 최소 권한 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

# installer가 만든 cron과 같은 renewal check
acme.sh --cron --home ~/.acme.sh
 
# upstream code upgrade
acme.sh --upgrade
 
# automatic upgrade 활성화 또는 비활성화
acme.sh --upgrade --auto-upgrade
acme.sh --upgrade --auto-upgrade 0

• 기본 program home: ~/.acme.sh/
• 기본 account configuration: ~/.acme.sh/account.conf
• domain별 발급·설치 상태: ~/.acme.sh/DOMAIN/DOMAIN.conf 또는 key type에 따른 domain directory
• installer는 기본적으로 daily cron entry와 shell alias를 만든다.
• 저장 위치, DNS credential, permission, 검증 workflow는 config를 참고한다.

• acme.sh: command not found: 새 terminal을 열거나 ~/.acme.sh/acme.sh 절대 경로를 사용한다. 다른 user로 실행하면 설치 home과 cron도 달라진다.
• HTTP-01 failure: public DNS, inbound TCP/80, webroot write permission과 challenge path의 reverse proxy routing을 확인한다.
• standalone bind failure: port 80 또는 443을 점유한 process와 필요한 privilege를 확인한다.
• DNS-01 failure: authoritative nameserver에서 TXT record를 조회하고 provider token의 zone/record permission과 propagation을 확인한다.
• 갱신됐지만 server certificate가 그대로인 경우: –install-cert destination, –reloadcmd, service config test 결과를 확인한다.
• CA account registration error: 선택한 –server, account email, External Account Binding 요구 사항을 확인한다.

• upstream은 Bash, dash, POSIX sh와 여러 Unix 계열 OS를 지원하고 Windows에서는 Cygwin 환경을 명시한다.
• DNS automation 지원 범위는 설치된 dnsapi/ hook과 provider API 변경에 따라 달라지므로 최신 upstream 문서를 확인한다.
• ECC certificate가 기본이다. legacy client가 RSA를 요구할 때만 compatibility를 확인하고 –keylength 2048 이상을 명시한다.

• DNS manual mode는 제거된 기능은 아니지만 unattended renewal을 지원하지 않는다. 자동화에는 provider DNS API hook 또는 다른 자동 validation 방식을 사용한다.
• 오래된 문서의 기본 CA, 기본 key type, renewal 주기 설명은 현재 version과 다를 수 있으므로 acme.sh –version, –info, 공식 README를 함께 확인한다.

+ acme.sh -h (upstream v3.1.5, command excerpt)

Usage: acme.sh <command> ... [parameters ...]
 
Commands:
  -h, --help               Show this help message.
  -v, --version            Show version info.
  --install                Install acme.sh to your system.
  --uninstall              Uninstall acme.sh, and uninstall the cron job.
  --upgrade                Upgrade acme.sh to the latest code.
  --issue                  Issue a cert.
  --deploy                 Deploy the cert to your server.
  -i, --install-cert       Install the issued cert to a server.
  -r, --renew              Renew a cert.
  --renew-all              Renew all the certs.
  --revoke                 Revoke a cert.
  --remove                 Remove the cert from the list known to acme.sh.
  --list                   List all the certs.
  --info                   Show global or domain configs.
  --cron                   Run cron job to renew all the certs.
  --set-default-ca         Set the default CA with --server.

+

• config
• acme
• certbot
• openssl
• https
• acme.sh official repository
• acme.sh official wiki

• codex:: 2026-07-19 Added the acme.sh CLI page with official installation, issuance, deployment, renewal, security, and troubleshooting guidance.