llm-wiki/raw/official-docs/certbot-user-guide.md

---
title: Certbot — User Guide (official-vendor-doc)
source_type: official-doc
url: https://eff-certbot.readthedocs.io/en/stable/using.html
archive_url:
status: raw
confidence: high
tags: [certbot, lets-encrypt, acme, nginx, tls, renewal, keycloak-https-termination]
related_projects: []
related_branches: [feature-keycloak-https-termination-caddy-nginx]
created: 2026-05-27
last_reviewed: 2026-05-27
---

# Certbot — User Guide (공식)

> Layer: `raw/official-docs/` — EFF Certbot 공식 사용자 가이드의 **원문 발췌·출처 기록**.
> Strength 분류: `official-vendor-doc` — EFF (Electronic Frontier Foundation) 가 maintain 하는 Certbot 의 공식 문서.
> 검증된 요약은 `/ingest` 후 `wiki/concepts/` 에 별도 작성.

## Parent / 활용 branch (필수)

| Branch | 이 자료가 정당화하는 결정 |
|---|---|
| [[raw/branch-notes/feature-keycloak-https-termination-caddy-nginx]] | **D3 (certbot CLI + renewal model)** 의 근거 — certbot 의 subcommand 체계 + automated renewal (preconfigured scheduled task) + nginx plugin 의 공식 명세. Caddy auto-HTTPS 대안으로 nginx + certbot 채택 시의 운영 모델 외부 근거. |

## 컨텍스트

`feature-keycloak-https-termination-caddy-nginx` 의 D3 은 "Caddy 대안으로 nginx + certbot 을 채택할 경우의 운영 모델" 을 다룬다. Certbot 의 user guide 는 (a) subcommand 체계 (`certonly`, `renew`, `run`), (b) automated renewal (scheduled task / `certbot renew`), (c) nginx plugin (`--nginx`), (d) 갱신 임계 (lifetime 의 1/3 미만), (e) hooks 를 직접 진술한다. 본 raw 는 D3 의 외부 근거로 보관.

## 출처 / Source

- 원본 URL: https://eff-certbot.readthedocs.io/en/stable/using.html
- 아카이브 URL: (미수집 — 추후 archive.org 스냅샷 추가)
- 저자 / 조직: EFF (Electronic Frontier Foundation) — Certbot project
- 발행일: rolling docs (Certbot 4.x stable)
- 마지막 확인일: 2026-05-27

## 핵심 인용 / Key quotes (verbatim)

> [§Certbot Commands] "Certbot uses a number of different commands (also referred to as \"subcommands\") to request specific actions such as obtaining, renewing, or revoking certificates."

> [§Automated Renewals] "Most Certbot installations come with automatic renewals preconfigured. This is done by means of a scheduled task which runs `certbot renew` periodically."

> [§Automated Renewals] "If you are unsure whether you need to configure automated renewal: Review the instructions for your system and installation method at https://certbot.eff.org/instructions. They will describe how to set up a scheduled task, if necessary."

> [§Nginx] "The Nginx plugin should work for most configurations. We recommend backing up Nginx configurations before using it (though you can also revert changes to configurations with `certbot --nginx rollback`)."

> [§Renewing certificates] "This command attempts to renew any previously-obtained certificates which are ready for renewal. As of Certbot 4.0.0, a certificate is considered ready for renewal when less than 1/3rd of its lifetime remains."

> [§Renewing certificates] "The `renew` command includes hooks for running commands or scripts before or after a certificate is renewed."

## Claims Extracted / 추출된 주장

| Claim ID | Claim (이 자료가 직접 말하는 것) | Evidence quote | Strength | Applies to | Does not prove |
|---|---|---|---|---|---|
| CERTBOT-UG-C1 | Certbot 은 certificate 의 obtain / renew / revoke 등 특정 동작을 **subcommand** 체계로 노출 | [§Certbot Commands] "Certbot uses a number of different commands (also referred to as \"subcommands\") to request specific actions such as obtaining, renewing, or revoking certificates." | `official-vendor-doc` | Certbot CLI 사용 시나리오 | subcommand 의 전체 목록 (`certonly`, `run`, `delete`, `revoke` 등) 은 본 인용에 명시되어 있지 않음 — 별도 reference 페이지 참조 |
| CERTBOT-UG-C2 | **대부분의 Certbot installation 은 automated renewal 이 preconfigured** 되어 있으며, 이는 `certbot renew` 를 주기적으로 실행하는 **scheduled task** 로 구현됨 | [§Automated Renewals] "Most Certbot installations come with automatic renewals preconfigured. This is done by means of a scheduled task which runs `certbot renew` periodically." | `official-vendor-doc` | OS 패키지 매니저 / snap 등 표준 installation 경로 | scheduled task 의 구체 구현 (systemd timer vs cron) 은 본 인용 범위 밖 — installation 방식 의존 (`C3` 참조) |
| CERTBOT-UG-C3 | scheduled task 의 구체 설정 방식은 system / installation method 별로 다르며, certbot.eff.org/instructions 에서 안내 | [§Automated Renewals] "Review the instructions for your system and installation method at https://certbot.eff.org/instructions. They will describe how to set up a scheduled task, if necessary." | `official-vendor-doc` | OS / installer 별 renewal 구성 차이 | "모든 OS 에서 systemd timer 가 default" 라는 뜻은 아님 — installation method 의존 |
| CERTBOT-UG-C4 | **Nginx plugin** (`--nginx`) 은 대부분의 구성에서 동작하며, 사용 전 nginx 설정 backup 권장. `certbot --nginx rollback` 으로 변경 되돌리기 가능 | [§Nginx] "The Nginx plugin should work for most configurations. We recommend backing up Nginx configurations before using it (though you can also revert changes to configurations with `certbot --nginx rollback`)." | `official-vendor-doc` | nginx + certbot 통합 시나리오 | "모든 nginx 설정에서 동작 보장" 이라는 뜻은 아님 ("should work for most") — edge case (복잡 server block 등) 는 manual config 필요 |
| CERTBOT-UG-C5 | `certbot renew` 는 이전에 발급된 cert 중 **갱신 준비된 것** 만 갱신 시도. **Certbot 4.0.0 부터** "갱신 준비됨" 의 기준은 **lifetime 의 1/3 미만 남음** | [§Renewing certificates] "This command attempts to renew any previously-obtained certificates which are ready for renewal. As of Certbot 4.0.0, a certificate is considered ready for renewal when less than 1/3rd of its lifetime remains." | `official-vendor-doc` | Certbot 4.0.0 이상 의 `certbot renew` 동작 | Certbot 4.0.0 이전 버전의 동일 임계 (90일 cert 의 30일 전 등) 가 본 정의와 동일하다는 뜻은 아님 — 이전 버전은 별도 changelog 확인 |
| CERTBOT-UG-C6 | `renew` 명령은 **갱신 전/후 명령 실행을 위한 hooks** 를 포함 (`--pre-hook`, `--post-hook`, `--deploy-hook`) | [§Renewing certificates] "The `renew` command includes hooks for running commands or scripts before or after a certificate is renewed." | `official-vendor-doc` | 갱신 시 nginx reload / 서비스 재시작 자동화 | hook flag 명 (`--pre-hook` 등) 의 구체 사용법은 본 인용 범위 밖 — 별도 reference 참조 |

## Usage Boundaries / 적용 경계

- **이 자료가 직접 증명하는 것**:
  - `CERTBOT-UG-C2`, `C3`: automated renewal 은 standard installation 의 default — scheduled task 가 미리 구성됨
  - `CERTBOT-UG-C4`: nginx plugin (`--nginx`) 의 공식 지원 + rollback 메커니즘
  - `CERTBOT-UG-C5`: Certbot 4.0.0 부터 renewal 임계는 lifetime 의 1/3 (e.g. 90일 cert 의 30일 전, 6일 short-lived cert 의 2일 전)
  - `CERTBOT-UG-C6`: renewal hooks 가 공식 지원됨 (nginx reload 자동화 가능)
- **이 자료가 증명하지 않는 것**:
  - **scheduled task 의 구체 구현이 systemd timer 인지 cron 인지** — `C3` 명시적으로 "installation method 의존" 이라 진술. Ubuntu 22.04 의 snap certbot 은 systemd timer (`snap.certbot.renew.timer`), apt-installed certbot 은 cron (`/etc/cron.d/certbot`) — 본 raw 가 직접 보증하지 않음
  - **`--nginx` plugin 이 nginx 설정을 어떻게 수정하는지** (예: `server` block 자동 추가, `ssl_certificate` directive 삽입) — `C4` 는 동작 보장만 진술
  - **manual mode 와 plugin mode 의 차이** — 본 raw 의 인용 범위 밖
  - **Caddy auto-HTTPS 대비 운영 비교** — 본 raw 는 certbot 자체만 진술
- **내 프로젝트에 적용하려면 추가 확인이 필요한 것**:
  - `feature-keycloak-https-termination-caddy-nginx` 의 D3 에서 nginx + certbot 채택 시, host OS / installation method 의 scheduled task 형식 확인 — Ubuntu/Debian/RHEL 별 다름
  - Keycloak 환경에서 `--deploy-hook="systemctl reload nginx"` 같은 hook 설정 — 본 raw 는 hook 의 존재만 보증, 구체 설정은 별도 검증
  - renewal 실패 시 alert 메커니즘 — certbot 자체는 exit code 만 반환, alerting 은 별도 (systemd `OnFailure=` 등)

## 메모 / Notes

- `C5` 는 **Certbot 4.0.0 변경점** — 이전 버전 (3.x 이하) 의 임계는 "만료 30일 전 (hard-coded)" 이었음. wiki/concepts 옮길 때 버전 명시 필수.
- `C2` 의 "Most Certbot installations" 는 **standard 패키지 매니저 경로** (apt/snap/dnf) 기준. source build / 수동 설치는 별도 scheduled task 구성 필요.
- D3 에서 "certbot renewal 은 zero-downtime" 같은 강한 진술 시 본 raw 로 보증 불가 — `--deploy-hook` 의 실제 동작 (예: `nginx -s reload` 의 graceful 여부) 은 nginx 측 보장.

## Related / 관련

- 같은 주제 다른 raw 자료: [[raw/official-docs/caddy-automatic-https-docs.md]] (auto-HTTPS 대안)
- 이 자료를 인용한 wiki 요약: (미작성)
- 이 자료를 인용하는 branch: [[raw/branch-notes/feature-keycloak-https-termination-caddy-nginx]]
- 인용하는 project: [[raw/project-notes/keycloak-patterns-overview]]