Certbot

Certbot은 ACME(Automatic Certificate Management Environment) protocol을 사용해 공개 TLS 인증서를 발급, 설치, 갱신, 폐기하는 CLI client다. 기본 CA는 Let's Encrypt이며 web server plugin이나 webroot, standalone, DNS plugin을 통해 domain control을 검증한다.

• 인증서 요청부터 domain validation, web server 설치, 자동 갱신까지 연결할 수 있다.
• run은 발급과 설치를 함께 처리하고, certonly는 인증서만 발급한다.
• 운영 적용 전 renew –dry-run과 staging CA로 자동 갱신 경로를 검증한다.
• ACME protocol과 challenge 선택은 acme에서 자세히 설명한다.

sudo certbot --nginx -d example.com -d www.example.com
sudo certbot certonly --webroot -w /var/www/html -d example.com
sudo certbot renew --dry-run
sudo certbot certificates

• certbot run [<options>…] -d DOMAIN…: 인증서를 발급하고 지원되는 web server에 설치한다.
• certbot certonly [<options>…] -d DOMAIN…: web server 설정을 바꾸지 않고 인증서만 발급한다.
• certbot renew [–dry-run] [–deploy-hook COMMAND]: 관리 중인 인증서의 갱신 시점을 확인하고 필요한 인증서를 갱신한다.
• certbot certificates: Certbot이 관리하는 인증서와 만료 정보를 표시한다.
• certbot revoke –cert-name NAME: 인증서를 폐기한다.
• certbot delete –cert-name NAME: 로컬에서 인증서 lineage를 삭제한다.

ACME는 CA와 client 사이의 account 생성, certificate order, identifier authorization, issuance, renewal, revocation을 자동화하는 RFC 8555 protocol이다. Certbot은 ACME client이며 Let's Encrypt는 대표적인 ACME server다.

• HTTP-01: http://DOMAIN/.well-known/acme-challenge/TOKEN을 port 80에서 제공한다. –nginx, –apache, –webroot, –standalone에서 주로 사용한다.
• DNS-01: _acme-challenge.DOMAIN의 TXT record로 domain control을 증명한다. wildcard 인증서에 필요하며 DNS API plugin을 쓰면 갱신을 자동화할 수 있다.
• TLS-ALPN-01: port 443의 ALPN 기반 검증 방식이다. ACME 표준 challenge지만 Certbot 설치와 plugin 조합에서 지원되는지 별도로 확인해야 한다.

자세한 challenge 선택 기준, wildcard 발급, staging server는 acme를 참고한다.

• -d, –domains DOMAIN: 인증서에 포함할 domain을 지정한다. 여러 번 사용할 수 있다.
• –nginx: Nginx authenticator와 installer를 사용한다.
• –apache: Apache authenticator와 installer를 사용한다.
• –webroot: 실행 중인 web server의 webroot에 HTTP-01 challenge file을 둔다.
• -w, –webroot-path PATH: –webroot가 사용할 document root를 지정한다.
• –standalone: Certbot의 임시 web server로 검증한다. 선택한 port가 비어 있고 외부에서 접근 가능해야 한다.
• –manual: challenge를 대화형으로 처리한다. hook이 없으면 자동 갱신할 수 없다.
• –preferred-challenges TYPE: http, dns 등 선호 challenge를 지정한다.
• –test-cert, –staging: CA staging server에서 시험 인증서를 요청한다.
• –dry-run: renew 또는 지원되는 certonly 흐름을 저장 없이 시험한다.
• –deploy-hook COMMAND: 인증서가 실제로 갱신된 뒤 실행할 command를 지정한다.

# Nginx 인증 및 설치
sudo certbot --nginx -d example.com -d www.example.com
 
# 기존 webroot를 이용해 인증서만 발급
sudo certbot certonly --webroot -w /var/www/html -d example.com
 
# port 80을 Certbot이 직접 사용
sudo certbot certonly --standalone -d example.com
 
# 자동 갱신 경로 시험
sudo certbot renew --dry-run
 
# 관리 중인 인증서 확인
sudo certbot certificates

• 기본 구성 파일: /etc/letsencrypt/cli.ini
• 인증서와 key의 현재 symlink: /etc/letsencrypt/live/CERT_NAME/
• 갱신 설정: /etc/letsencrypt/renewal/CERT_NAME.conf
• hook directory: /etc/letsencrypt/renewal-hooks/{pre,deploy,post}/
• 개별 renewal configuration을 직접 편집하는 방식은 갱신을 깨뜨릴 수 있으므로 command option으로 변경한 뒤 renew –dry-run으로 검증한다.

• HTTP-01 실패 시 public DNS가 해당 server를 가리키는지, inbound TCP/80이 열려 있는지, redirect 뒤에도 challenge path가 제공되는지 확인한다.
• DNS-01 실패 시 authoritative DNS에 _acme-challenge TXT record가 전파됐는지와 delegation/CNAME 구성을 확인한다.
• standalone bind 실패 시 port 80 또는 443을 점유한 service를 확인한다. 운영 중단이 필요하면 service manager와 maintenance window를 먼저 준비한다.
• 갱신 후 service가 새 인증서를 읽지 않으면 –deploy-hook으로 config test와 reload를 연결한다.
• renew의 exit status 0은 실제 갱신뿐 아니라 갱신 대상이 없다는 뜻일 수도 있다. 실제 갱신 후 동작은 deploy hook으로 판단한다.

• 사용 가능한 authenticator와 installer는 설치한 Certbot plugin에 따라 달라진다. certbot plugins로 확인한다.
• 배포판 package는 최신 upstream보다 오래될 수 있다. 설치 방식은 installation을 참고한다.
• wildcard certificate는 DNS-01 validation이 필요하다.

+ certbot --help (local certbot 1.22.0)

certbot [SUBCOMMAND] [options] [-d DOMAIN] [-d DOMAIN] ...
 
Common subcommands:
  run           Obtain and install a certificate
  certonly      Obtain or renew a certificate without installing it
  renew         Renew certificates that are near expiry
  certificates  Display managed certificates
  revoke        Revoke a certificate
  delete        Delete a certificate lineage
 
Common authenticators/installers:
  --apache  --nginx  --standalone  --webroot  --manual
 
Testing and automation:
  -n, --non-interactive
  --test-cert
  --dry-run
 
Use "certbot -h all" or "certbot --help TOPIC" for detailed local help.

+

• installation
• acme

• acme-sh
• openssl
• https
• caddy
• mkcert
• Certbot documentation
• RFC 8555: ACME

• codex:: 2026-07-19 Linked the acme.sh CLI reference as an alternative ACME client.
• codex:: 2026-07-19 Created the Certbot language head page with ACME discovery, certificate workflows, renewal, and troubleshooting guidance.