acme-sh:ko [Command Line Interface Helper]

이 문서는 읽기 전용입니다. 원본을 볼 수는 있지만 바꿀 수는 없습니다. 문제가 있다고 생각하면 관리자에게 문의하세요.
{{tag>[cli acme-sh acme tls ssl https certificate letsencrypt zerossl]}}

====== acme.sh ======

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

===== Summary =====
  * 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''로 운영 경로에 복사한다.

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

==== Online Installer ====
사용자가 제공한 공식 설치 예시다. ''you@example.com''을 실제 ACME account 연락처로 바꾼다.

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

<note warning>
''curl | sh''는 network에서 받은 script를 즉시 실행한다. 보안 정책상 검토가 필요하면 먼저 file로 내려받아 내용을 확인한 뒤 실행한다. email, API token, private key 같은 실제 secret을 wiki나 Git에 기록하지 않는다.
</note>

<code bash>
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
</code>

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

<code bash>
~/.acme.sh/acme.sh --version
acme.sh --version
</code>

==== Git ====
<code bash>
git clone https://github.com/acmesh-official/acme.sh.git
cd acme.sh
./acme.sh --install -m you@example.com
</code>

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

===== Usage =====
<code bash>
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
</code>

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

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

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

<code bash>
acme.sh --set-default-ca --server letsencrypt
</code>

==== Webroot ====
<code bash>
# 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
</code>

==== Standalone ====
<code bash>
acme.sh --issue --standalone -d example.com
</code>

<note important>
standalone mode는 port 80이 비어 있어야 하며 NAT, firewall, load balancer를 통과해 CA가 접근할 수 있어야 한다. 운영 web server 중지가 필요하면 maintenance window를 먼저 준비한다.
</note>

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

provider별 variable 이름과 최소 권한은 반드시 공식 [[https://github.com/acmesh-official/acme.sh/wiki/dnsapi|DNS API 문서]]에서 확인한다.

==== Certificate 설치 ====
아래 예시는 acme.sh를 root account에 설치해 root cron으로 갱신하는 server를 가정한다. 일반 user로 설치했다면 해당 user에게 쓸 수 있는 destination과 password 입력 없이 실행 가능한 최소 권한 reload 방식을 별도로 구성한다.

<code bash>
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
</code>

<note important>
''~/.acme.sh/DOMAIN/''은 acme.sh 내부 저장소이며 구조가 바뀔 수 있다. web server가 이 경로를 직접 읽게 하지 말고 ''--install-cert''와 ''--reloadcmd''를 사용한다. destination의 owner와 permission을 먼저 구성하고 갱신 후 실제 service가 새 certificate를 읽는지 확인한다.
</note>

==== 갱신과 Upgrade ====
<code bash>
# 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
</code>

<note warning>
''--renew --force''를 정기 작업에 사용하지 않는다. 불필요한 재발급은 CA rate limit을 소모한다. 정상 cron 실행은 certificate 상태와 CA의 renewal information을 기준으로 필요한 대상만 처리한다.
</note>

===== Config =====
  * 기본 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는 [[acme-sh:config:ko]]를 참고한다.

===== Troubleshooting =====
  * ''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 요구 사항을 확인한다.

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

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

===== Help =====
+++ acme.sh -h (upstream v3.1.5, command excerpt) |
<code text>
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.
</code>
+++

===== See Also =====
  * [[acme-sh:config:ko]]
  * [[certbot:acme:ko]]
  * [[certbot:ko]]
  * [[openssl:ko]]
  * [[nginx:config:https]]
  * [[https://github.com/acmesh-official/acme.sh|acme.sh official repository]]
  * [[https://github.com/acmesh-official/acme.sh/wiki|acme.sh official wiki]]

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

{{indexmenu>.#1|js}}