`gitlab-sshd`

요약

gitlab-sshd는 Go로 작성된 독립형 SSH 서버입니다. OpenSSH가 제한된 쉘 접근 방식을 사용하는 반면 gitlab-sshd는: 구현에 대한 자세한 내용은 블로그 게시물을 참조하세요. OpenSSH에서 gitlab-sshd로 전환을 고려하고 있다면 다음을 고려하세요:

gitlab-sshd는 Go로 작성된 독립형 SSH 서버입니다. OpenSSH의 경량 대안입니다. gitlab-shell 패키지의 일부이며 SSH 작업을 처리합니다.

OpenSSH가 제한된 쉘 접근 방식을 사용하는 반면 gitlab-sshd는:

현대적인 멀티스레드 서버 애플리케이션으로 기능합니다.
SSH 전송 프로토콜 대신 원격 프로시저 호출(RPC)을 사용합니다.
OpenSSH보다 메모리를 덜 사용합니다.
프록시 뒤에서 실행되는 애플리케이션에 대해 IP 주소별 그룹 액세스 제한을 지원합니다.

구현에 대한 자세한 내용은 블로그 게시물을 참조하세요.

OpenSSH에서 gitlab-sshd로 전환을 고려하고 있다면 다음을 고려하세요:

PROXY 프로토콜: gitlab-sshd는 PROXY 프로토콜을 지원하여 HAProxy와 같은 프록시 서버 뒤에서 실행할 수 있습니다. 이 기능은 기본적으로 활성화되어 있지 않지만 활성화할 수 있습니다.
SSH 인증서: gitlab-sshd는 config.yml에 구성된 신뢰할 수 있는 CA 키를 사용하여 인스턴스 수준의 SSH 인증서 인증을 지원합니다. 자세한 내용은 gitlab-sshd를 사용한 인스턴스 수준 SSH 인증서를 참조하세요.
2FA 복구 코드: gitlab-sshd는 2FA 복구 코드 재생성을 지원하지 않습니다. 2fa_recovery_codes를 실행하려고 하면 remote: ERROR: Unknown command: 2fa_recovery_codes 오류가 발생합니다. 자세한 내용은 토론을 참조하세요.

GitLab Shell의 기능은 Git 작업을 넘어 확장되며 GitLab과의 다양한 SSH 기반 상호 작용에 사용될 수 있습니다.

`gitlab-sshd` 활성화#

gitlab-sshd를 사용하려면:

다음 지침은 OpenSSH와 다른 포트에서 gitlab-sshd를 활성화합니다:

/etc/gitlab/gitlab.rb를 편집합니다:

gitlab_sshd['enable'] = true
gitlab_sshd['listen_address'] = '[::]:2222' # Adjust the port accordingly

선택 사항. 기본적으로 Linux 패키지 설치는 /var/opt/gitlab/gitlab-sshd에 없는 경우 gitlab-sshd에 대한 SSH 호스트 키를 생성합니다. 이 자동 생성을 비활성화하려면 다음 줄을 추가합니다:
```
gitlab_sshd['generate_host_keys'] = false
```
파일을 저장하고 GitLab을 재구성합니다:
```
sudo gitlab-ctl reconfigure
```

기본적으로 gitlab-sshd는 git 사용자로 실행됩니다. 결과적으로 gitlab-sshd는 1024보다 낮은 권한 있는 포트 번호에서 실행할 수 없습니다. 이는 사용자가 gitlab-sshd 포트로 Git에 액세스하거나 SSH 트래픽을 gitlab-sshd 포트로 전달하는 로드 밸런서를 사용하여 이를 숨겨야 함을 의미합니다.

새로 생성된 호스트 키가 OpenSSH 호스트 키와 다르기 때문에 사용자에게 호스트 키 경고가 표시될 수 있습니다. 이것이 문제인 경우 호스트 키 생성을 비활성화하고 기존 OpenSSH 호스트 키를 /var/opt/gitlab/gitlab-sshd에 복사하는 것을 고려하세요.

다음 지침은 gitlab-sshd를 위해 OpenSSH를 전환합니다:

gitlab-shell 차트 sshDaemon 옵션을 gitlab-sshd로 설정합니다. 예를 들어:
```
gitlab:
  gitlab-shell:
    sshDaemon: gitlab-sshd
```
Helm 업그레이드를 수행합니다.

기본적으로 gitlab-sshd는 다음을 수신합니다:

포트 22의 외부 요청(global.shell.port).
포트 2222의 내부 요청(gitlab.gitlab-shell.service.internalPort).

Helm 차트에서 다른 포트를 구성할 수 있습니다.

메트릭#

gitlab-sshd는 gitlab-shell 구성에서 web_listen으로 구성된 모니터링 엔드포인트에 Prometheus 메트릭을 노출합니다. gitlab-sshd는 해당 주소의 /metrics 경로에서 메트릭을 제공합니다.

Metric	Type	Description
gitlab_shell_sshd_in_flight_connections	Gauge	gitlab-sshd가 현재 처리 중인 연결 수입니다.
gitlab_shell_sshd_concurrent_limited_sessions_total	Counter	동시 세션 제한에 도달한 횟수입니다.
gitlab_shell_sshd_session_duration_seconds	Histogram	gitlab-sshd가 처리한 SSH 세션의 지속 시간입니다.
gitlab_shell_sshd_session_established_duration_seconds	Histogram	SSH 세션이 설정될 때까지의 지연 시간이며, gitlab_sshd 서비스 Apdex의 지연 시간으로 사용됩니다.
gitlab_sli:shell_sshd_sessions:total	Counter	설정된 SSH 세션(인증 후 세션 채널) 수입니다.
gitlab_sli:shell_sshd_sessions:errors_total	Counter	실패한 SSH 세션 수입니다.
gitlab_sli:shell_sshd_connections:total	Counter	인증 단계에 도달한 SSH 연결 수입니다.
gitlab_sli:shell_sshd_connections:errors_total	Counter	서버 측 오류로 인해 실패한 SSH 연결 수입니다.

세션 수준 및 연결 수준 SLI#

gitlab-sshd는 SSH 안정성을 위한 두 가지 서비스 수준 지표(SLI) 카운터 세트를 노출합니다:

세션 수준(gitlab_sli:shell_sshd_sessions:*)은 인증 후 세션 채널을 계산합니다. 이 카운터는 인증 단계에서 발생하는 실패를 관찰하지 않습니다.
연결 수준(gitlab_sli:shell_sshd_connections:*)은 인증 단계에 도달하는 각 연결을 계산하며, 인증 또는 세션 단계에서 발생하는 서버 측 오류를 실패로 처리합니다. 세션 수준 카운터와 달리 연결 수준 카운터는 authorized_keys 조회 오류와 같은 인증 단계 실패를 포착합니다. 연결 수준 카운터는 포트 스캐너 및 상태 확인과 같이 전송 핸드셰이크를 통과하지 못한 연결을 제외합니다.

연결 수준 카운터는 사용자에게 영향을 미치는 실패를 더 광범위하게 포괄하며 SSH 안정성 모니터링에 선호되는 신호입니다.

기타 GitLab Shell 메트릭#

gitlab-sshd는 GitLab Shell이 다른 서비스와 수행하는 상호 작용에 대한 메트릭도 노출합니다. 이 메트릭은 GitLab Shell의 일반적인 계측의 일부이며 SSH 데몬에만 국한되지 않습니다. 이 메트릭은 Gitaly, GitLab 내부 API, Git LFS, Topology Service에 대한 연결을 포괄합니다. gitlab-sshd가 SSH 연결을 처리할 때 gitlab-sshd는 이러한 작업을 자체 프로세스에서 실행하고 결과 카운터를 SSH 메트릭과 동일한 /metrics 엔드포인트에 노출합니다. gitlab-sshd 대신 OpenSSH를 사용하는 경우 GitLab Shell은 각 연결에 대해 수명이 짧은 프로세스로 실행됩니다. 이러한 수명이 짧은 프로세스는 동일한 카운터를 증가시키지만 메트릭 엔드포인트를 노출하지 않으므로 카운터를 스크래핑할 수 없습니다.

Metric	Type	Description
gitlab_shell_gitaly_connections_total	Counter	설정된 Gitaly 연결 수이며, 상태(ok 또는 fail)별로 레이블이 지정됩니다.
gitlab_shell_http_requests_total	Counter	GitLab 내부 API에 대한 요청 수이며, 코드 및 메서드별로 레이블이 지정됩니다.
gitlab_shell_http_request_duration_seconds	Histogram	GitLab 내부 API에 대한 요청 지연 시간이며, 코드 및 메서드별로 레이블이 지정됩니다.
gitlab_shell_http_in_flight_requests	Gauge	현재 수행 중인 GitLab 내부 API 요청 수입니다.
lfs_http_connections_total	Counter	설정된 Git LFS-over-HTTP 연결 수입니다.
lfs_ssh_connections_total	Counter	설정된 Git LFS-over-SSH 연결 수입니다.
gitlab_shell_topology_connections_total	Counter	설정된 Topology Service 연결 수이며, 상태(ok 또는 fail)별로 레이블이 지정됩니다.
gitlab_shell_topology_requests_total	Counter	Topology Service Classify 요청 수이며, 상태(ok 또는 fail)별로 레이블이 지정됩니다.
gitlab_shell_topology_request_duration_seconds	Histogram	Topology Service Classify 요청의 지연 시간입니다.

PROXY 프로토콜 지원#

gitlab-sshd 앞에 있는 로드 밸런서로 인해 GitLab이 클라이언트 IP 주소 대신 프록시 IP 주소를 보고합니다. 실제 IP 주소를 얻으려면 gitlab-sshd가 PROXY 프로토콜을 지원합니다.

PROXY 프로토콜을 활성화하려면:

/etc/gitlab/gitlab.rb를 편집합니다:

gitlab_sshd['proxy_protocol'] = true
# Proxy protocol policy ("use", "require", "reject", "ignore"), "use" is the default value
gitlab_sshd['proxy_policy'] = "use"

gitlab_sshd['proxy_policy'] 옵션에 대한 자세한 내용은 go-proxyproto 라이브러리를 참조하세요.

파일을 저장하고 GitLab을 재구성합니다:
```
sudo gitlab-ctl reconfigure
```

gitlab.gitlab-shell.config 옵션을 설정합니다. 예를 들어:

gitlab:
  gitlab-shell:
    config:
      proxyProtocol: true
      proxyPolicy: "use"

Helm 업그레이드를 수행합니다.

`gitlab-sshd`

GitLab v19.2

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

원문 보기

번역일: 2026-07-17

요약

gitlab-sshd는 Go로 작성된 독립형 SSH 서버입니다. OpenSSH의 경량 대안입니다. gitlab-shell 패키지의 일부이며 SSH 작업을 처리합니다.

OpenSSH가 제한된 쉘 접근 방식을 사용하는 반면 gitlab-sshd는:

현대적인 멀티스레드 서버 애플리케이션으로 기능합니다.
SSH 전송 프로토콜 대신 원격 프로시저 호출(RPC)을 사용합니다.
OpenSSH보다 메모리를 덜 사용합니다.
프록시 뒤에서 실행되는 애플리케이션에 대해 IP 주소별 그룹 액세스 제한을 지원합니다.

구현에 대한 자세한 내용은 블로그 게시물을 참조하세요.

OpenSSH에서 gitlab-sshd로 전환을 고려하고 있다면 다음을 고려하세요:

PROXY 프로토콜: gitlab-sshd는 PROXY 프로토콜을 지원하여 HAProxy와 같은 프록시 서버 뒤에서 실행할 수 있습니다. 이 기능은 기본적으로 활성화되어 있지 않지만 활성화할 수 있습니다.
SSH 인증서: gitlab-sshd는 config.yml에 구성된 신뢰할 수 있는 CA 키를 사용하여 인스턴스 수준의 SSH 인증서 인증을 지원합니다. 자세한 내용은 gitlab-sshd를 사용한 인스턴스 수준 SSH 인증서를 참조하세요.
2FA 복구 코드: gitlab-sshd는 2FA 복구 코드 재생성을 지원하지 않습니다. 2fa_recovery_codes를 실행하려고 하면 remote: ERROR: Unknown command: 2fa_recovery_codes 오류가 발생합니다. 자세한 내용은 토론을 참조하세요.

GitLab Shell의 기능은 Git 작업을 넘어 확장되며 GitLab과의 다양한 SSH 기반 상호 작용에 사용될 수 있습니다.

`gitlab-sshd` 활성화#

gitlab-sshd를 사용하려면:

다음 지침은 OpenSSH와 다른 포트에서 gitlab-sshd를 활성화합니다:

/etc/gitlab/gitlab.rb를 편집합니다:

gitlab_sshd['enable'] = true
gitlab_sshd['listen_address'] = '[::]:2222' # Adjust the port accordingly

선택 사항. 기본적으로 Linux 패키지 설치는 /var/opt/gitlab/gitlab-sshd에 없는 경우 gitlab-sshd에 대한 SSH 호스트 키를 생성합니다. 이 자동 생성을 비활성화하려면 다음 줄을 추가합니다:
```
gitlab_sshd['generate_host_keys'] = false
```
파일을 저장하고 GitLab을 재구성합니다:
```
sudo gitlab-ctl reconfigure
```

다음 지침은 gitlab-sshd를 위해 OpenSSH를 전환합니다:

gitlab-shell 차트 sshDaemon 옵션을 gitlab-sshd로 설정합니다. 예를 들어:
```
gitlab:
  gitlab-shell:
    sshDaemon: gitlab-sshd
```
Helm 업그레이드를 수행합니다.

기본적으로 gitlab-sshd는 다음을 수신합니다:

포트 22의 외부 요청(global.shell.port).
포트 2222의 내부 요청(gitlab.gitlab-shell.service.internalPort).

Helm 차트에서 다른 포트를 구성할 수 있습니다.

메트릭#

Metric	Type	Description
gitlab_shell_sshd_in_flight_connections	Gauge	gitlab-sshd가 현재 처리 중인 연결 수입니다.
gitlab_shell_sshd_concurrent_limited_sessions_total	Counter	동시 세션 제한에 도달한 횟수입니다.
gitlab_shell_sshd_session_duration_seconds	Histogram	gitlab-sshd가 처리한 SSH 세션의 지속 시간입니다.
gitlab_shell_sshd_session_established_duration_seconds	Histogram	SSH 세션이 설정될 때까지의 지연 시간이며, gitlab_sshd 서비스 Apdex의 지연 시간으로 사용됩니다.
gitlab_sli:shell_sshd_sessions:total	Counter	설정된 SSH 세션(인증 후 세션 채널) 수입니다.
gitlab_sli:shell_sshd_sessions:errors_total	Counter	실패한 SSH 세션 수입니다.
gitlab_sli:shell_sshd_connections:total	Counter	인증 단계에 도달한 SSH 연결 수입니다.
gitlab_sli:shell_sshd_connections:errors_total	Counter	서버 측 오류로 인해 실패한 SSH 연결 수입니다.

세션 수준 및 연결 수준 SLI#

gitlab-sshd는 SSH 안정성을 위한 두 가지 서비스 수준 지표(SLI) 카운터 세트를 노출합니다:

세션 수준(gitlab_sli:shell_sshd_sessions:*)은 인증 후 세션 채널을 계산합니다. 이 카운터는 인증 단계에서 발생하는 실패를 관찰하지 않습니다.
연결 수준(gitlab_sli:shell_sshd_connections:*)은 인증 단계에 도달하는 각 연결을 계산하며, 인증 또는 세션 단계에서 발생하는 서버 측 오류를 실패로 처리합니다. 세션 수준 카운터와 달리 연결 수준 카운터는 authorized_keys 조회 오류와 같은 인증 단계 실패를 포착합니다. 연결 수준 카운터는 포트 스캐너 및 상태 확인과 같이 전송 핸드셰이크를 통과하지 못한 연결을 제외합니다.

연결 수준 카운터는 사용자에게 영향을 미치는 실패를 더 광범위하게 포괄하며 SSH 안정성 모니터링에 선호되는 신호입니다.

기타 GitLab Shell 메트릭#

Metric	Type	Description
gitlab_shell_gitaly_connections_total	Counter	설정된 Gitaly 연결 수이며, 상태(ok 또는 fail)별로 레이블이 지정됩니다.
gitlab_shell_http_requests_total	Counter	GitLab 내부 API에 대한 요청 수이며, 코드 및 메서드별로 레이블이 지정됩니다.
gitlab_shell_http_request_duration_seconds	Histogram	GitLab 내부 API에 대한 요청 지연 시간이며, 코드 및 메서드별로 레이블이 지정됩니다.
gitlab_shell_http_in_flight_requests	Gauge	현재 수행 중인 GitLab 내부 API 요청 수입니다.
lfs_http_connections_total	Counter	설정된 Git LFS-over-HTTP 연결 수입니다.
lfs_ssh_connections_total	Counter	설정된 Git LFS-over-SSH 연결 수입니다.
gitlab_shell_topology_connections_total	Counter	설정된 Topology Service 연결 수이며, 상태(ok 또는 fail)별로 레이블이 지정됩니다.
gitlab_shell_topology_requests_total	Counter	Topology Service Classify 요청 수이며, 상태(ok 또는 fail)별로 레이블이 지정됩니다.
gitlab_shell_topology_request_duration_seconds	Histogram	Topology Service Classify 요청의 지연 시간입니다.

PROXY 프로토콜 지원#

PROXY 프로토콜을 활성화하려면:

/etc/gitlab/gitlab.rb를 편집합니다:

gitlab_sshd['proxy_protocol'] = true
# Proxy protocol policy ("use", "require", "reject", "ignore"), "use" is the default value
gitlab_sshd['proxy_policy'] = "use"

gitlab_sshd['proxy_policy'] 옵션에 대한 자세한 내용은 go-proxyproto 라이브러리를 참조하세요.

파일을 저장하고 GitLab을 재구성합니다:
```
sudo gitlab-ctl reconfigure
```

gitlab.gitlab-shell.config 옵션을 설정합니다. 예를 들어:

gitlab:
  gitlab-shell:
    config:
      proxyProtocol: true
      proxyPolicy: "use"

Helm 업그레이드를 수행합니다.

`gitlab-sshd`

gitlab-sshd 활성화#

메트릭#

세션 수준 및 연결 수준 SLI#

기타 GitLab Shell 메트릭#

PROXY 프로토콜 지원#

`gitlab-sshd`

gitlab-sshd 활성화#

메트릭#

세션 수준 및 연결 수준 SLI#

기타 GitLab Shell 메트릭#

PROXY 프로토콜 지원#

`gitlab-sshd` 활성화#

`gitlab-sshd` 활성화#