TLS에서 조정할 수 있는 것

Pingclair의 TLS 표면은 의도적으로 작습니다. 이름은 자동으로 인증서를 받고, 그 방식 을 결정하는 설정이 여기 적힌 것들입니다. Caddy가 받아들이는 나머지는 조용히 무시되지 않고 이름을 대며 거부되므로, 설정이 이름보다 조용히 적게 하지는 않습니다. 이 페이지는 실제 호스트에서 측정한 “실제로 되는 것”과 “안 되는 것”을 모은 것입니다.

🧾 시작하기 전에

Pingclair가 설치되어 실행 중이어야 합니다(설치).
인증 기관과 관련된 부분에서는 호스트로 해석되는 이름, 또는 실험용 내부 인증 기관 (HTTPS).

🌐 어떤 프로토콜을 서비스하는가

프로토콜 집합은 전역 servers 블록에 있습니다.

{
    servers {
        protocols h1 h2 h3
    }
}

sudo ss -lun | grep ':443 '로 측정:

설정	UDP 443 리스너
`protocols h1 h2`	0 — HTTP/3 없음
`protocols h1 h2 h3`	1 — HTTP/3 켜짐

⚠️ 이 목록이 결정하는 것은 HTTP/3뿐입니다. h1만 적어도 HTTP/2는 빠지지 않습니다. protocols h1에서도 ALPN으로 h2를 제시한 클라이언트는 HTTP/2를 협상했습니다. 컴파일러는 이 목록을 HTTP/3 스위치에 대응시킬 뿐입니다 (config.global.http3 = protocols.contains(H3)). 이름별로 HTTP/2를 끄는 설정은 없습니다.

사이트 단위에서는 http3 off가 QUIC 리스너를 멈추지 않고 그 이름을 HTTP/3에서 빼냅니다.

https://internal.test {
    tls {
        internal
        http3 off
    }
    file_server /srv/site
}

🏛️ 인증서 출처

세 가지이며 모두 HTTPS 페이지에 있습니다.

출처	설정	용도
Let’s Encrypt	공개 이름 그대로	공개 이름. 백그라운드에서 갱신.
내부 인증 기관	`tls internal`	실험용 이름, 사설 오리진, 터널.
직접 만든 파일	`tls { cert … key … }`	다른 곳에서 발급한 인증서.

갱신은 스스로 돌아갑니다. 전역 옵션의 renewal_window_ratio는 각 인증서 수명의 얼마나 일찍 갱신을 시작할지를 비율로 정합니다.

🔐 클라이언트 인증서

client_auth는 클라이언트 인증서를 요구합니다. openssl로 작은 인증 기관과 클라이언트 인증서를 만들고, 사이트를 인증 기관 파일로 향하게 합니다.

https://internal.test {
    tls {
        internal
        client_auth {
            mode require_and_verify
            trusted_ca_cert_file /etc/pingclair/client-ca.crt
        }
    }
    file_server /srv/site
}

측정: 클라이언트 인증서 없는 요청은 핸드셰이크에서 실패하고, --cert client.crt --key client.key를 붙인 같은 요청은 200을 답합니다.

모드는 request, require, verify_if_given, require_and_verify이며 대체가 없습니다. 철자를 틀리면 (expected request, require, verify_if_given or require_and_verify)라는 목록과 함께 거부됩니다.

⚠️ trusted_ca_cert는 인증서를 인라인으로 받고, trusted_ca_cert_file은 경로를 받습니다. 전자에 경로를 주면 컴파일은 되고 시작할 때 trusted_ca_cert is not a certificate: not valid base64: Invalid symbol 45로 실패합니다(-----BEGIN의 -). 파일은 pingclair 사용자가 읽을 수 있어야 합니다.

📦 인증서 저장소 옮기기

저장소에는 발급된 인증서, ACME 계정, 내부 인증 기관이 들어 있고, 그 자리는 /var/lib/pingclair/.local/share/pingclair——서비스 계정의 데이터 디렉터리입니다. 다른 사용자로 돌릴 때 PINGCLAIR_TLS_STORE가 그것을 가리킵니다(아래 예시가 접두사를 붙이는 이유이고, root의 기본값은 /root/.local/share/pingclair입니다). storage-export와 storage-import가 그것을 옮깁니다.

sudo PINGCLAIR_TLS_STORE=/var/lib/pingclair/.local/share/pingclair pingclair storage-export -o /tmp/store.tar
sudo systemctl stop pingclair
sudo rm -rf /var/lib/pingclair/.local/share/pingclair
sudo mkdir -p /var/lib/pingclair/.local/share/pingclair && sudo chown pingclair:pingclair /var/lib/pingclair/.local/share/pingclair
sudo PINGCLAIR_TLS_STORE=/var/lib/pingclair/.local/share/pingclair pingclair storage-import -i /tmp/store.tar
sudo systemctl start pingclair

✅ Store exported to /tmp/store.tar
✅ Store imported into /var/lib/pingclair/.local/share/pingclair

실행에서 나온 세 가지. 아카이브는 이름과 무관하게 그냥 tar이고 모드 600으로 쓰이므로 다시 읽으려면 root가 필요합니다. 가져오기는 아카이브에 기록된 소유권을 그대로 복원합니다. 그리고 저장소에는 autosave.json(Admin API가 마지막으로 적용한 설정)도 들어 있어 함께 돌아옵니다.

그 뒤 서비스가 Internal CA I/O error: Permission denied로 시작을 거부하면 저장소 파일을 서비스 계정이 쓸 수 없는 것입니다. sudo chown -R pingclair:pingclair /var/lib/pingclair/.local/share/pingclair로 고쳐지고 사이트가 다시 응답합니다.

🚫 조정할 수 없는 것

다음은 Pingclair가 인식하고 거부하는 Caddy 설정입니다. 설정이 조용히 빠진 채 실행되는 일은 없습니다.

Caddy-compatible directive 'tls ciphers' is not supported by Pingclair yet: Pingclair does not implement this TLS option yet
Caddy-compatible directive 'tls curves' is not supported by Pingclair yet: Pingclair does not implement this TLS option yet
Caddy-compatible directive 'tls alpn' is not supported by Pingclair yet: Pingclair does not implement this TLS option yet
Caddy-compatible directive 'tls on_demand' is not supported by Pingclair yet: Pingclair does not implement this TLS option yet

즉 암호 스위트, 곡선, ALPN 목록, 온디맨드 발급은 설정이 아니라 빌드의 선택입니다. OCSP 스테이플링과 preferred_chains도 구현되어 있지 않습니다. 이 중 하나가 필요하다면 설정 실수가 아니라 기능 요청입니다.

⚠️ 잘 되지 않을 때

client_auth가 not valid base64로 시작을 거부. trusted_ca_cert에 경로를 주었습니다. 파일용 철자는 trusted_ca_cert_file입니다.
유효한 인증서를 가진 클라이언트가 거부됨. 서명한 인증 기관이 trusted_ca_cert_file의 그것인지, 인증서가 만료되지 않았는지 확인하십시오.
tls ciphers / tls curves / tls alpn / tls on_demand가 파일을 거부. 구현되어 있지 않습니다. 위 절을 보십시오.
protocols h1 h2인데 HTTP/3가 계속 동작. 그래서는 안 됩니다. 그것을 정하는 것이 이 목록입니다. UDP 443이 아직 듣고 있다면 실행 중인 파일이 편집한 파일이 아닙니다(재적용의 의미).
저장소를 옮긴 뒤 서비스가 시작하지 않음. 위의 소유권 문제입니다.

🧭 다음 단계

HTTPS: 인증서를 얻는 네 가지 방법과 그대로의 로그 줄.
HTTP/3: 켜고, 클라이언트가 실제로 썼음을 증명하는 방법.
tls: 지시어 레퍼런스.

🛡️TLS에서 조정할 수 있는 것