Namecheap DNS 헬퍼 (A/TXT 레코드)
Namecheap DNS 레코드 안전하게 추가/삭제하는 헬퍼 사용법.
Namecheap setHosts API, 모든 레코드 덮어씀. destructive.
직접 curl 쓰면 기존 레코드 날려먹기 쉬움.
그래서 만들어둔 헬퍼(GET-then-SET 패턴) 재사용함.
파일 위치
스크립트: /home/son/prj/log/deploy/namecheap_dns.py
자격증명: /home/son/prj/log/.env
NAMECHEAP_API_USER
NAMECHEAP_API_KEY
NAMECHEAP_USERNAME
NAMECHEAP_CLIENT_IP
계정 정보 (헷갈리지 말 것)
ApiUser / UserName은 urustin (도메인 이름 ericfromkorea 아님).
ericfromkorea로 시도 시 error 1011102 났었음.
ClientIp는 .env의 NAMECHEAP_CLIENT_IP (집 공유기 WAN IP).
Namecheap API Access 화이트리스트에 등록돼 있어야 함.
WAN IP 바뀌면 Namecheap 대시보드에서 재등록 필요.
CLI 사용법 A 레코드 추가/업데이트 (멱등성):
cd /home/son/prj/log
SITE_DOMAIN=[도메인].ericfromkorea.com PUBLIC_IP=[공개 IP] \
.venv/bin/python deploy/namecheap_dns.py a
출력: created / updated / unchanged 중 하나.
TXT 레코드 (Let's Encrypt DNS-01 챌린지용):
cd /home/son/prj/log
.venv/bin/python deploy/namecheap_dns.py txt-add [챌린지 도메인] "<value>"
.venv/bin/python deploy/namecheap_dns.py txt-del [챌린지 도메인] "<value>"
Python에서 직접 import할 때
from deploy.namecheap_dns import ensure_a_record, add_txt_record, remove_txt_record
ensure_a_record("foo.ericfromkorea.com", "125.131.103.44") # 결과: "created"|"updated"|"unchanged"
add_txt_record("_acme-challenge.foo.ericfromkorea.com", "abc123")
remove_txt_record("_acme-challenge.foo.ericfromkorea.com", "abc123")
내부적으로 getHosts -> 변경 -> setHosts 패턴. 다른 레코드들 보존됨.
DNS 전파 대기
Namecheap TTL 기본 1800초.
dig +short [FQDN] @8.8.8.8 로 확인. 보통 몇 분 내 보임.
새 서브도메인, NXDOMAIN -> 정답 바뀌는 데 1~10분 정도.
여기서 배울 것
- Namecheap `setHosts` API의 destructive 특성 인지.
- `GET-then-SET` 패턴으로 DNS 레코드 안전하게 조작.
- Namecheap API `ApiUser` / `UserName` 혼동 주의.
- DNS 전파 시간 및 `dig`로 확인하는 법.
원본 파일 보기 (.claude/skills/tn-namecheap-dns/SKILL.md)
---
name: Namecheap DNS 헬퍼 (A/TXT 레코드 안전 추가/수정)
description: Use when adding or updating an A or TXT DNS record on a Namecheap-managed domain (e.g. *.ericfromkorea.com), including subdomain provisioning before SSL issuance and Let's Encrypt DNS-01 challenge. Reuses an existing safe helper instead of writing curl from scratch.
version: 1.0.0
---
# Namecheap DNS 조작 헬퍼
Namecheap의 `setHosts` API는 **모든 레코드를 덮어쓰는 destructive API**다.
직접 curl로 짜면 기존 레코드를 날려먹기 쉬우므로, 이미 만들어둔 헬퍼(GET-then-SET 패턴)를 재사용한다.
## 파일 위치
- 스크립트: `/home/son/prj/log/deploy/namecheap_dns.py`
- 자격증명: `/home/son/prj/log/.env`
- `NAMECHEAP_API_USER`, `NAMECHEAP_API_KEY`, `NAMECHEAP_USERNAME`, `NAMECHEAP_CLIENT_IP`
## 계정 정보 — 헷갈리지 말 것
- `ApiUser` / `UserName`은 **`urustin`** (도메인 이름 `ericfromkorea`가 아님).
- 과거에 `ericfromkorea`로 시도하다 `error 1011102` 받은 기록 있음.
- `ClientIp`는 `.env`의 `NAMECHEAP_CLIENT_IP` (가정용 공유기 WAN IP).
Namecheap API Access 화이트리스트에 등록되어 있어야 호출 성공.
WAN IP 바뀌면 Namecheap 대시보드에서 재등록 필요.
## CLI 사용법
A 레코드 추가/업데이트 (멱등):
```bash
cd /home/son/prj/log
SITE_DOMAIN=foo.ericfromkorea.com PUBLIC_IP=125.131.103.44 \
.venv/bin/python deploy/namecheap_dns.py a
# 출력: created / updated / unchanged
```
TXT 레코드 (Let's Encrypt DNS-01 챌린지용):
```bash
cd /home/son/prj/log
.venv/bin/python deploy/namecheap_dns.py txt-add _acme-challenge.foo.ericfromkorea.com "<value>"
.venv/bin/python deploy/namecheap_dns.py txt-del _acme-challenge.foo.ericfromkorea.com "<value>"
```
## 함수 (Python에서 직접 import할 때)
```python
from deploy.namecheap_dns import ensure_a_record, add_txt_record, remove_txt_record
ensure_a_record("foo.ericfromkorea.com", "125.131.103.44") # → "created"|"updated"|"unchanged"
add_txt_record("_acme-challenge.foo.ericfromkorea.com", "abc123")
remove_txt_record("_acme-challenge.foo.ericfromkorea.com", "abc123")
```
내부적으로 항상 `getHosts` → 변경 → 전체 `setHosts` 패턴이라 다른 레코드는 보존된다.
## DNS 전파 대기
- Namecheap TTL 기본 1800초.
- `dig +short <fqdn> @8.8.8.8` 로 확인. 보통 분 단위 내에 보임.
- 새 서브도메인은 NXDOMAIN → 정답으로 바뀌는 데 통상 1~10분.