Linux 패키지 설치에 대한 SSL 구성

Tier: Free, Premium, Ultimate Offering: Self-Managed

Linux 패키지는 SSL 구성에 대한 여러 일반적인 사용 사례를 지원합니다.

기본적으로 HTTPS가 활성화되어 있지 않습니다. HTTPS를 활성화하려면 다음을 수행할 수 있습니다:

  • 무료로 자동화된 HTTPS를 제공하는 Let’s Encrypt 사용
  • 직접 SSL을 구성
note
SSL을 종료하기 위해 프록시, 로드 밸런서 또는 기타 외부 장치를 사용하는 경우 GitLab 호스트 이름에 대해 외부, 프록시 및 로드 밸런서 SSL 종료를 참조하세요.

다음 표에는 각 GitLab 서비스가 지원하는 방법이 나와 있습니다.

서비스 매뉴얼 SSL Let’s Encrypt 통합
GitLab 인스턴스 도메인 예 예
컨테이너 레지스트리 예 예
Mattermost 예 예
GitLab Pages 예 아니요

Let’s Encrypt 통합 활성화

Let’s Encrypt는 external_url이 HTTPS 프로토콜로 설정되어 있고 다른 인증서가 구성되어 있지 않은 경우 기본적으로 활성화됩니다.

전제 조건:

  • 공용 Let’s Encrypt 서버에서 검증 검사를 실행하는 포트 80 및 443에 액세스할 수 있어야 합니다. 검증은 비표준 포트에서 작동하지 않습니다. 환경이 비공개이거나 오프라인인 경우 Let’s Encrypt에서 사용하는 도구인 certbot은 매뉴얼 방법으로 Let’s Encrypt 인증서를 설치합니다.

Let’s Encrypt 활성화하려면:

  1. /etc/gitlab/gitlab.rb을 편집하고 다음 항목을 추가하거나 변경합니다: 

    ## GitLab 인스턴스
external_url "https://gitlab.example.com"         # 반드시 https 프로토콜을 사용
letsencrypt['contact_emails'] = ['foo@email.com'] # 선택 사항
   
## 컨테이너 레지스트리 (선택 사항), 반드시 https 프로토콜을 사용해야 함
registry_external_url "https://registry.example.com"
#registry_nginx['ssl_certificate'] = "path/to/cert"      # 반드시 없거나 주석 처리되어 있어야 함
   
## Mattermost (선택 사항), 반드시 https 프로토콜을 사용해야 함
mattermost_external_url "https://mattermost.example.com"
    • 인증서의 유효 기간은 90일입니다. contact_emails에 지정한 이메일 주소는 인증서 만료일에 경고를 받습니다.
    • GitLab 인스턴스는 인증서의 기본 도메인 이름이며, 컨테이너 레지스트리와 같은 추가 서비스는 같은 인증서의 대체 도메인 이름으로 추가됩니다. 위의 예에서 기본 도메인은 gitlab.example.com이고 컨테이너 레지스트리 도메인은 registry.example.com입니다. 와일드카드 인증서를 설정할 필요가 없습니다.

  2. GitLab을 다시 구성합니다: 

    sudo gitlab-ctl reconfigure

Let’s Encrypt이 인증서를 발급하지 못하는 경우 잠재적인 해결 방법에 대해서는 문제 해결 섹션을 참조하세요.

자동으로 인증서 갱신

기본 설치는 매월 4일 자정 후에 갱신을 예약합니다. 분은 external_url의 값에 따라 결정되어 상위 Let’s Encrypt 서버의 부하를 분산하는 데 도움이 됩니다.

갱신 시간을 명시적으로 설정하려면:

  1. /etc/gitlab/gitlab.rb을 편집합니다. 

    # 월별 7일에 12:30 갱신
letsencrypt['auto_renew_hour'] = "12"
letsencrypt['auto_renew_minute'] = "30"
letsencrypt['auto_renew_day_of_month'] = "*/7"

  2. GitLab을 다시 구성합니다: 

    sudo gitlab-ctl reconfigure
note
인증서가 30일 내에 만료되면 인증서는 갱신되기 전에 만료됩니다. 예를 들어, 매월 1일 00:00에 갱신하도록 설정하고 인증서가 31일에 만료되면 인증서는 갱신되기 전에 만료됩니다.

자동 갱신은 go-crond로 관리됩니다. 원하는 경우 /etc/gitlab/gitlab.rb를 편집하여 CLI 인수를 go-crond에 전달할 수 있습니다.

자동 갱신을 비활성화하려면:

  1. /etc/gitlab/gitlab.rb을 편집합니다: 

    letsencrypt['auto_renew'] = false

  2. GitLab을 다시 구성합니다: 

    sudo gitlab-ctl reconfigure

매뉴얼으로 인증서 갱신

다음 중 하나의 명령을 사용하여 Let’s Encrypt 인증서를 매뉴얼으로 갱신합니다: 

sudo gitlab-ctl reconfigure

sudo gitlab-ctl renew-le-certs

인증서가 만료 직전에만 갱신명령이 실행됩니다. 갱신 중에 오류가 발생하는 경우 상위 속도 제한을 고려하세요.

Let’s Encrypt 이외의 ACME 서버 사용

Let’s Encrypt 이외의 ACME 서버를 사용하여 인증서를 가져올 수 있으며 GitLab을 구성할 수 있습니다. 자체 ACME 서버를 제공하는 일부 서비스는 다음과 같습니다:

사용자 지정 ACME 서버를 구성하려면:

  1. /etc/gitlab/gitlab.rb을 편집하고 ACME 엔드포인트를 설정합니다: 

    external_url 'https://example.com'
letsencrypt['acme_staging_endpoint'] = 'https://ca.internal/acme/acme/directory'
letsencrypt['acme_production_endpoint'] = 'https://ca.internal/acme/acme/directory'

    사용자 정의 ACME 서버가 제공하는 경우 테스트 엔드포인트를 사용하세요. 먼저 테스트 엔드포인트를 확인하여 ACME 구성이 올바른지 확인한 후 ACME 프로덕션에 요청을 제출합니다. 이를 통해 ACME 요청을 제출할 때 ACME 속도 제한을 피할 수 있습니다. 기본 값은 다음과 같습니다: 

    https://acme-staging-v02.api.letsencrypt.org/directory
https://acme-v02.api.letsencrypt.org/directory

  2. GitLab을 다시 구성합니다: 

    sudo gitlab-ctl reconfigure

인증서에 대체 도메인 추가

Let’s Encrypt 인증서에 대체 도메인(또는 주체 대안 이름)을 추가할 수 있습니다. 이는 bundled NGINX를 [백엔드 응용 프로그램에 대한 리버스 프록시로 사용]하려는 경우 유용할 수 있습니다.

대체 도메인의 DNS 레코드는 GitLab 인스턴스를 가리켜야 합니다.

다음을 수행하여 Let’s Encrypt 인증서에 대체 도메인을 추가합니다:

  1. /etc/gitlab/gitlab.rb을 편집하고 대체 도메인을 추가합니다: 

     # 여러 도메인은 쉼표로 구분합니다
 letsencrypt['alt_names'] = ['another-application.example.com']

  2. GitLab을 다시 구성합니다: 

    sudo gitlab-ctl reconfigure

GitLab 애플리케이션의 결과 Let’s Encrypt 인증서에는 지정된 대체 도메인이 포함됩니다. 생성된 파일은 다음 위치에 있습니다:

  • 키: /etc/gitlab/ssl/gitlab.example.com.key
  • 인증서: /etc/gitlab/ssl/gitlab.example.com.crt

매뉴얼으로 HTTPS 구성하기

caution
NGINX 구성은 브라우저와 클라이언트에게 HSTS를 사용하여 다음 365일 동안 귀하의 GitLab 인스턴스와 안전한 연결만 가능하도록 지시합니다. 더 많은 구성 옵션은 HTTP Strict Transport Security(HSTS) 구성를 참조하십시오. HTTPS를 활성화하려면 적어도 다음 24개월 동안 인스턴스에 안전한 연결을 제공해야 합니다.

HTTPS를 활성화하려면:

  1. /etc/gitlab/gitlab.rb 파일을 편집합니다:

    1. external_url을 도메인으로 설정합니다. URL에 https가 있는지 확인하십시오: ruby external_url "https://gitlab.example.com"

    2. Let’s Encrypt 통합을 비활성화합니다: ruby letsencrypt['enable'] = false

      GitLab은 reconfigure 할 때마다 Let’s Encrypt 인증서를 갱신하려고 시도합니다. 매뉴얼으로 생성된 인증서를 사용할 계획이라면 Let’s Encrypt 통합을 비활성화해야 합니다. 그렇지 않으면 자동 갱신으로 인해 인증서가 덮어쓰일 수 있습니다.

  2. /etc/gitlab/ssl 디렉터리를 생성하고 키 및 인증서를 복사합니다: shell sudo mkdir -p /etc/gitlab/ssl sudo chmod 755 /etc/gitlab/ssl sudo cp gitlab.example.com.key gitlab.example.com.crt /etc/gitlab/ssl/

    위 예제에서 호스트명은 gitlab.example.com이며, Linux 패키지 설치는 각각 /etc/gitlab/ssl/gitlab.example.com.key 및 /etc/gitlab/ssl/gitlab.example.com.crt라는 개인 키 및 공용 인증서 파일을 찾습니다. 원하는 경우 다른 위치 및 인증서 이름을 사용할 수 있습니다.

    클라이언트가 SSL 오류를 방지하기 위해 올바른 순서로 전체 인증서 체인을 사용해야 합니다. 먼저 서버 인증서, 그 다음 중간 인증서들, 마지막으로 루트 CA를 순서대로 사용해야 합니다.

  3. 선택 사항. certificate.key 파일이 암호로 보호된 경우 NGINX는 GitLab을 reconfigure할 때 암호를 요구하지 않습니다. 이 경우 Linux 패키지 설치 프로세스가 오류 메시지 없이 조용히 실패합니다.

    키 파일의 암호를 지정하려면 암호를 텍스트 파일(예: /etc/gitlab/ssl/key_file_password.txt)에 저장하고 다음을 /etc/gitlab/gitlab.rb에 추가하십시오: ruby nginx['ssl_password_file'] = '/etc/gitlab/ssl/key_file_password.txt'

  4. GitLab을 reconfigure 합니다: shell sudo gitlab-ctl reconfigure

  5. 선택 사항. 방화벽을 사용하는 경우 인바운드 HTTPS 트래픽을 허용하기 위해 포트 443을 열어야 할 수 있습니다: ```shell # UFW 예제 (Debian, Ubuntu) sudo ufw allow https

    lokkit 예제 (RedHat, CentOS 6)

    sudo lokkit -s https

    firewall-cmd (RedHat, Centos 7)

    sudo firewall-cmd –permanent –add-service=https sudo systemctl reload firewalld ```

기존 인증서를 업데이트하는 경우 다른 프로세스를 따라야 합니다.

HTTP 요청을 HTTPS로 리디렉션하기

기본적으로 external_url에 https로 시작하는 경우 NGINX는 미암호화된 HTTP 트래픽을 더 이상 포트 80에서 수신하지 않습니다. 모든 HTTP 트래픽을 HTTPS로 리디렉션하려면:

  1. /etc/gitlab/gitlab.rb 파일을 편집합니다: ruby nginx['redirect_http_to_https'] = true

  2. GitLab을 reconfigure 합니다: shell sudo gitlab-ctl reconfigure

note
이 동작은 Let’s Encrypt 통합을 사용하는 경우 기본적으로 활성화됩니다.

기본 HTTPS 포트 변경

기본 HTTPS 포트(443) 이외의 HTTPS 포트를 사용해야 하는 경우 external_url의 일부로 지정합니다:

  1. /etc/gitlab/gitlab.rb 파일을 편집합니다: ruby external_url "https://gitlab.example.com:2443"

  2. GitLab을 reconfigure 합니다: shell sudo gitlab-ctl reconfigure

기본 SSL 인증서 위치 변경

호스트명이 gitlab.example.com인 경우 Linux 패키지 설치는 기본적으로 /etc/gitlab/ssl/gitlab.example.com.key라는 개인 키와 /etc/gitlab/ssl/gitlab.example.com.crt라는 공용 인증서를 찾습니다.

SSL 인증서의 다른 위치를 설정하려면:

  1. 디렉터리를 생성하고 적절한 권한을 부여한 후 .crt 및 .key 파일을 디렉터리에 배치합니다: shell sudo mkdir -p /mnt/gitlab/ssl sudo chmod 755 /mnt/gitlab/ssl sudo cp gitlab.key gitlab.crt /mnt/gitlab/ssl/

    클라이언트가 SSL 오류를 방지하기 위해 올바른 순서로 전체 인증서 체인을 사용해야 합니다. 먼저 서버 인증서, 그 다음 중간 인증서들, 마지막으로 루트 CA를 순서대로 사용해야 합니다.

  2. /etc/gitlab/gitlab.rb 파일을 편집합니다: ruby nginx['ssl_certificate'] = "/mnt/gitlab/ssl/gitlab.crt" nginx['ssl_certificate_key'] = "/mnt/gitlab/ssl/gitlab.key"

  3. GitLab을 reconfigure 합니다: shell sudo gitlab-ctl reconfigure

SSL 인증서 업데이트

SSL 인증서의 내용이 업데이트되었지만 /etc/gitlab/gitlab.rb에 구성 변경이 없는 경우 GitLab을 reconfigure 해도 NGINX에는 영향을 주지 않습니다. 대신 NGINX를 새로운 인증서로 재로드하도록 해야 합니다: 

sudo gitlab-ctl hup nginx
sudo gitlab-ctl hup registry

역방향 프록시 또는 로드 밸런서 SSL 종료 구성

기본적으로 Linux 패키지 설치는 external_url이 https://를 포함하고 있다면 SSL을 사용할 것인지 자동 감지하고 NGINX를 SSL 종료하기 위해 구성합니다. 그러나 GitLab을 역방향 프록시 또는 외부 로드 밸런서 뒤에서 실행하도록 구성했다면 일부 환경에서는 애플리케이션 외부에서 SSL 종료를 해야 할 수 있습니다.

번들된 NGINX가 SSL 종료를 처리하지 않도록하려면:

  1. /etc/gitlab/gitlab.rb 파일을 편집합니다: ruby nginx['listen_port'] = 80 nginx['listen_https'] = false

  2. GitLab을 reconfigure 합니다: shell sudo gitlab-ctl reconfigure

외부 로드 밸런서는 200 상태 코드를 반환하는 GitLab 엔드포이트에 액세스할 수 있어야 합니다(로그인이 필요한 설치의 경우 루트 페이지는 로그인 페이지로의 302 리디렉션을 반환합니다). 이 경우 상태 체크 엔드포인트를 사용하는 것이 권장됩니다.

컨테이너 레지스트리, GitLab Pages, Mattermost 등의 기타 번들 컴포넌트들도 프록시된 SSL을 위해 유사한 전략을 사용합니다. 특정 컴포넌트의 *_external_url에 https://를 사용하고 nginx[...] 구성을 해당 컴포넌트 이름과 접두사로 사용합니다. 예를 들어, GitLab 컨테이너 레지스트리 구성은 registry_로 접두사가 붙습니다:

  1. /etc/gitlab/gitlab.rb 파일을 편집합니다: ```ruby registry_external_url ‘https://registry.example.com’

    registry_nginx[‘listen_port’] = 80 registry_nginx[‘listen_https’] = false ```

    동일한 형식을 Pages(pages_ 접두사), Mattermost(mattermost_ 접두사)에도 사용할 수 있습니다.

  2. GitLab을 reconfigure 합니다: shell sudo gitlab-ctl reconfigure

  3. 선택 사항. 역방향 프록시나 로드 밸런서에서 GitLab과(그리고 사용 중인 경우 Mattermost)에 특정 헤더(예: Host, X-Forwarded-Ssl, X-Forwarded-For, X-Forwarded-Port)를 전달하도록 설정해야 할 수 있습니다. 이 단계를 빼 먹으면 “422 Unprocessable Entity”나 “CSRF 토큰의 신뢰성을 확인할 수 없음”과 같은 잘못된 리디렉션 또는 오류가 표시될 수 있습니다.

AWS Certificate Manager (ACM)과 같은 일부 클라우드 제공자는 인증서를 다운로드하는 것을 허용하지 않습니다. 이로 인해 GitLab 인스턴스에서 종료할 수 없게 됩니다. 그러한 클라우드 서비스와 GitLab 사이에 SSL이 필요한 경우 GitLab 인스턴스에서 다른 인증서를 사용해야 합니다.

사용자 정의 SSL 암호 사용

기본적으로 Linux 패키지 SSL 암호를 사용하며 이는 테스트 및 GitLab 커뮤니티의 다양한 모범 사례로 조합된 결과입니다.

SSL 암호를 변경하려면:

  1. /etc/gitlab/gitlab.rb 파일을 편집하세요: 

    nginx['ssl_ciphers'] = "CIPHER:CIPHER1"

  2. GitLab을 다시 구성하세요: 

    sudo gitlab-ctl reconfigure

ssl_dhparam 지시문을 활성화하려면:

  1. dhparams.pem을 생성하세요: 

    openssl dhparam -out /etc/gitlab/ssl/dhparams.pem 2048

  2. /etc/gitlab/gitlab.rb 파일을 편집하세요: 

    nginx['ssl_dhparam'] = "/etc/gitlab/ssl/dhparams.pem"

  3. GitLab을 다시 구성하세요: 

    sudo gitlab-ctl reconfigure

HTTP/2 프로토콜 구성

기본적으로 GitLab 인스턴스가 HTTPS를 통해 접근 가능하다고 지정하면 HTTP/2 프로토콜도 사용할 수 있게 됩니다.

Linux 패키지는 HTTP/2 프로토콜과 호환되는 필수 SSL 암호를 설정합니다.

사용자 정의 SSL 암호를 지정하고 해당 암호가 HTTP/2 암호 블랙리스트에 있는 경우, GitLab 인스턴스에 액세스하려고 하면 브라우저에서 INADEQUATE_SECURITY 오류가 발생합니다. 이 경우 암호 디렉터리에서 문제가 되는 암호를 제거하는 것을 고려해야 합니다. 암호를 변경하는 것은 매우 구체적인 사용자 설정이 있는 경우에만 필요합니다.

HTTP/2 프로토콜을 활성화하는 이유에 대한 자세한 정보는 NGINX HTTP/2 whitepaper를 확인하세요.

암호를 변경하는 것이 불가능한 경우, HTTP/2 지원을 비활성화할 수 있습니다:

  1. /etc/gitlab/gitlab.rb 파일을 편집하세요: 

    nginx['http2_enabled'] = false

  2. GitLab을 다시 구성하세요: 

    sudo gitlab-ctl reconfigure
note
HTTP/2 설정은 GitLab 메인 애플리케이션에만 적용되며 GitLab Pages, 컨테이너 레지스트리, Mattermost와 같은 다른 서비스에는 적용되지 않습니다.

양방향 SSL 클라이언트 인증 활성화

웹 클라이언트가 신뢰할 수 있는 인증서로 인증하도록 요구하려면 2-way SSL을 활성화할 수 있습니다:

  1. /etc/gitlab/gitlab.rb 파일을 편집하세요: 

    nginx['ssl_verify_client'] = "on"
nginx['ssl_client_certificate'] = "/etc/pki/tls/certs/root-certs.pem"

  2. 선택 사항. NGINX가 클라이언트가 유효한 인증서를 갖고 있지 않다고 결정하기 전에 인증서 체인을 얼마나 깊게 확인해야 하는지 구성할 수 있습니다(기본값은 1). /etc/gitlab/gitlab.rb 파일을 편집하세요: 

    nginx['ssl_verify_depth'] = "2"

  3. GitLab을 다시 구성하세요: 

    sudo gitlab-ctl reconfigure

HTTP Strict Transport Security (HSTS) 구성

note
HSTS 설정은 GitLab 메인 애플리케이션에만 적용되며 GitLab Pages, 컨테이너 레지스트리, Mattermost와 같은 다른 서비스에는 적용되지 않습니다.

HTTP Strict Transport Security (HSTS)는 기본적으로 활성화되어 있으며 이를 통해 브라우저에 HTTPS를 통해만 웹사이트에 연락해야 한다는 정보가 제공됩니다. 브라우저가 한 번이라도 GitLab 인스턴스를 방문하면 사용자가 명시적으로 일반적인 HTTP URL(http://)을 입력하여도 브라우저가 자동으로 https://로 리디렉션되어 안전하지 않은 연결을 시도하지 않는다는 사실을 기억합니다.

기본값으로 max_age는 브라우저가 오직 HTTPS를 통해 연결해야 하는 기간으로 설정되어 있으며 이 값은 브라우저가 기억하는 기간입니다.

max age 값을 변경하려면:

  1. /etc/gitlab/gitlab.rb 파일을 편집하세요: 

    nginx['hsts_max_age'] = 63072000
nginx['hsts_include_subdomains'] = false

    max_age를 0으로 설정하면 HSTS가 비활성화됩니다.

  2. GitLab을 다시 구성하세요: 

    sudo gitlab-ctl reconfigure

HSTS와 NGINX에 대한 자세한 정보는 https://www.nginx.com/blog/http-strict-transport-security-hsts-and-nginx/를 참조하세요.

사용자 정의 공인 인증서 설치

어떤 환경은 다양한 작업을 위해 외부 리소스에 연결하고 GitLab은 이러한 연결이 HTTPS를 사용하도록 허용하며 자체 서명된 인증서를 지원합니다. GitLab에는 개별 사용자 정의 인증서를 /etc/gitlab/trusted-certs 디렉터리에 넣어 인증서 번들에 추가하는 기능이 있습니다. 이들은 공식 Mozilla 신뢰 기관 컬렉션을 사용하여 신뢰할 수 있는 루트 인증서의 인증서 유효성을 확인하는 데 사용됩니다.

note
자체 서명된 인증서를 사용하는 설치에 대해서는 Linux 패키지가 이러한 인증서를 관리하는 방법을 제공합니다. 이 작업이 어떻게 동작하는지의 기술적인 세부사항에 대한 자세한 내용은 이 페이지 하단의 세부 정보를 참조하세요.

사용자 정의 공인 인증서를 설치하려면:

  1. 개인 키 인증서에서 PEM 또는 DER 인코딩된 공인 인증서를 생성하세요.
  2. 공인 인증서 파일만 /etc/gitlab/trusted-certs 디렉터리에 복사하세요. 멀티노드 설치인 경우, 모든 노드에 인증서를 복사하는지 확인하세요.
    • GitLab을 사용하여 사용자 정의 공인 인증서를 사용하도록 구성하는 경우, 기본적으로 GitLab은 도메인 이름에 .crt 확장자가 있는 인증서를 찾기를 기대합니다. 예를 들어 서버 주소가 https://gitlab.example.com인 경우 인증서는 gitlab.example.com.crt로 이름이 지정되어 있어야 합니다.
    • GitLab이 사용해야 하는 외부 리소스에 연결하려면 .crt 확장자로 주어진 디렉터리에 인증서를 저장하세요. 파일 이름을 관련 외부 리소스의 도메인 이름을 기반으로 지정할 필요는 없지만 일관된 명명 방식을 사용하는 것이 도움이 됩니다.

    기본 SSL 인증서 위치를 변경하려면 기본 SSL 인증서 위치 변경할 수 있습니다.

  3. GitLab을 다시 구성하세요: 

    sudo gitlab-ctl reconfigure

사용자 정의 인증서 체인 사용

사용자 정의 인증서 체인을 사용하는 경우 알려진 문제로 인해 서버, 중간 및 루트 인증서를 /etc/gitlab/trusted-certs 디렉터리에 별도의 파일에 넣어야 합니다.

이는 GitLab 자체 또는 GitLab이 연결해야 하는 외부 리소스가 사용하는 커스텀 인증서 체인의 경우 모두 해당됩니다.

예를 들어 GitLab 자체에 대해서 사용하는 경우:

  • /etc/gitlab/trusted-certs/example.gitlab.com.crt
  • /etc/gitlab/trusted-certs/example.gitlab.com_intermediate.crt
  • /etc/gitlab/trusted-certs/example.gitlab.com_root.crt

GitLab이 연결해야 하는 외부 리소스를 위해 사용하는 경우:

  • /etc/gitlab/trusted-certs/external-service.gitlab.com.crt
  • /etc/gitlab/trusted-certs/external-service.gitlab.com_intermediate.crt
  • /etc/gitlab/trusted-certs/external-service.gitlab.com_root.crt

GitLab 및 SSL 작동 방식에 대한 세부 정보

Linux 패키지에는 자체 OpenSSL 라이브러리가 포함되어 있으며 모든 컴파일된 프로그램(예: Ruby, PostgreSQL 등)을 이 라이브러리에 링크합니다. 이 라이브러리는 /opt/gitlab/embedded/ssl/certs에서 인증서를 찾도록 컴파일됩니다.

Linux 패키지는 c_rehash 도구를 사용하여 /etc/gitlab/trusted-certs/에 추가된 모든 인증서를 /opt/gitlab/embedded/ssl/certs로 심볼릭 링크를 통해 관리합니다. 예를 들어, /etc/gitlab/trusted-certs/에 customcacert.pem을 추가한다고 가정해 봅시다. 

$ sudo ls -al /opt/gitlab/embedded/ssl/certs

total 272
drwxr-xr-x 2 root root   4096 Jul 12 04:19 .
drwxr-xr-x 4 root root   4096 Jul  6 04:00 ..
lrwxrwxrwx 1 root root     42 Jul 12 04:19 7f279c95.0 -> /etc/gitlab/trusted-certs/customcacert.pem
-rw-r--r-- 1 root root 263781 Jul  5 17:52 cacert.pem
-rw-r--r-- 1 root root    147 Feb  6 20:48 README

여기서 인증서의 지문은 7f279c95이며, 이는 사용자 정의 인증서를 가리킵니다.

HTTPS 요청을 하면 어떤 일이 벌어질까요? 간단한 루비 프로그램을 살펴보겠습니다. 

#!/opt/gitlab/embedded/bin/ruby
require 'openssl'
require 'net/http'

Net::HTTP.get(URI('https://www.google.com'))

이것이 뒷단에서 벌어지는 일입니다.

  1. “require openssl” 줄은 인터프리터가 /opt/gitlab/embedded/lib/ruby/2.3.0/x86_64-linux/openssl.so를 로드하도록 합니다.
  2. Net::HTTP 호출은 /opt/gitlab/embedded/ssl/certs/cacert.pem에 있는 기본 인증서 번들을 읽으려고 시도합니다.
  3. SSL 협상이 발생합니다.
  4. 서버가 SSL 인증서를 보냅니다.
  5. 보낸 인증서가 번들에 포함되어 있는 경우, SSL이 성공적으로 완료됩니다.
  6. 그렇지 않은 경우, OpenSSL은 사전 정의된 인증서 디렉터리 내에서 지문과 일치하는 파일을 찾아 다른 인증서를 유효성 검사할 수 있습니다. 예를 들어 인증서가 지문 7f279c95를 가지고 있다면, OpenSSL은 /opt/gitlab/embedded/ssl/certs/7f279c95.0를 읽으려고 시도할 것입니다.

참고로 OpenSSL 라이브러리는 SSL_CERT_FILE 및 SSL_CERT_DIR 환경 변수를 지원합니다. 전자는 로드할 기본 인증서 번들을 정의하고, 후자는 더 많은 인증서를 검색할 디렉터리를 정의합니다. trusted-certs 디렉터리에 인증서를 추가했다면 이러한 변수가 필요하지는 않을 것입니다. 그러나 어떠한 이유로든 이러한 변수를 설정해야 하는 경우 환경 변수로 정의할 수 있습니다. 예를 들어: 

gitlab_rails['env'] = {"SSL_CERT_FILE" => "/usr/lib/ssl/private/customcacert.pem"}

문제 해결

SSL에 대한 문제 해결 가이드는 여기에서 확인할 수 있습니다.