acme.sh는 POSIX shell로 작성된 ACME client다. certificate 발급, 자동 갱신, server 배포, DNS API validation을 하나의 script로 처리하며 기본 설치는 user의 ~/.acme.sh/ 아래에 command와 상태를 저장한다.
~/.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 | sh는 network에서 받은 script를 즉시 실행한다. 보안 정책상 검토가 필요하면 먼저 file로 내려받아 내용을 확인한 뒤 실행한다. email, API token, private key 같은 실제 secret을 wiki나 Git에 기록하지 않는다.
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
~/.acme.sh/DOMAIN/은 acme.sh 내부 저장소이며 구조가 바뀔 수 있다. web server가 이 경로를 직접 읽게 하지 말고 –install-cert와 –reloadcmd를 사용한다. destination의 owner와 permission을 먼저 구성하고 갱신 후 실제 service가 새 certificate를 읽는지 확인한다.
# 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
–renew –force를 정기 작업에 사용하지 않는다. 불필요한 재발급은 CA rate limit을 소모한다. 정상 cron 실행은 certificate 상태와 CA의 renewal information을 기준으로 필요한 대상만 처리한다.
~/.acme.sh/~/.acme.sh/account.conf~/.acme.sh/DOMAIN/DOMAIN.conf 또는 key type에 따른 domain directoryacme.sh: command not found: 새 terminal을 열거나 ~/.acme.sh/acme.sh 절대 경로를 사용한다. 다른 user로 실행하면 설치 home과 cron도 달라진다.–install-cert destination, –reloadcmd, service config test 결과를 확인한다.–server, account email, External Account Binding 요구 사항을 확인한다.sh와 여러 Unix 계열 OS를 지원하고 Windows에서는 Cygwin 환경을 명시한다.dnsapi/ hook과 provider API 변경에 따라 달라지므로 최신 upstream 문서를 확인한다.–keylength 2048 이상을 명시한다.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.
+