debian-mirror-gitlab/doc/administration/operations/gitlab_sshd.md

stage	group	info
Create	Source Code	To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments

gitlab-sshd (FREE SELF)

• Introduced in GitLab 14.5 as an Alpha release for self-managed customers.
• Ready for production use with Cloud Native GitLab in GitLab 15.1 and Omnibus GitLab in GitLab 15.9.

gitlab-sshd is a standalone SSH server written in Go. It is provided as a part of the gitlab-shell package. It has a lower memory use as a OpenSSH alternative, and supports group access restriction by IP address for applications running behind the proxy.

gitlab-sshd is a lightweight alternative to OpenSSH for providing SSH operations. While OpenSSH uses a restricted shell approach, gitlab-sshd behaves more like a modern multi-threaded server application, responding to incoming requests. The major difference is that OpenSSH uses SSH as a transport protocol while gitlab-sshd uses Remote Procedure Calls (RPCs). See the blog post for more details.

The capabilities of GitLab Shell are not limited to Git operations.

If you are considering switching from OpenSSH to gitlab-sshd, consider these concerns:

• gitlab-sshd supports the PROXY protocol. It can run behind proxy servers that rely on it, such as HAProxy. The PROXY protocol is not enabled by default, but it can be enabled.
• gitlab-sshd does not support SSH certificates. For more details, read issue #495.

Enable gitlab-sshd

To use gitlab-sshd:

::Tabs

:::TabTitle Linux package (Omnibus)

The following instructions enable gitlab-sshd on a different port than OpenSSH:

1. Edit /etc/gitlab/gitlab.rb:

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

2. Optional. By default, Omnibus GitLab generates SSH host keys for gitlab-sshd if they do not exist in /var/opt/gitlab/gitlab-sshd. If you wish to disable this automatic generation, add this line:

   gitlab_sshd['generate_host_keys'] = false
   

3. Save the file and reconfigure GitLab:

   sudo gitlab-ctl reconfigure
   

By default, gitlab-sshd runs as the git user. As a result, gitlab-sshd cannot run on privileged port numbers lower than 1024. This means users must access Git with the gitlab-sshd port, or use a load balancer that directs SSH traffic to the gitlab-sshd port to hide this.

Users may see host key warnings because the newly-generated host keys differ from the OpenSSH host keys. Consider disabling host key generation and copy the existing OpenSSH host keys into /var/opt/gitlab/gitlab-sshd if this is an issue.

:::TabTitle Helm chart (Kubernetes)

The following instructions switch OpenSSH in favor of gitlab-sshd:

1. Set the gitlab-shell charts sshDaemon option to gitlab-sshd. For example:

   gitlab:
     gitlab-shell:
       sshDaemon: gitlab-sshd
   

2. Perform a Helm upgrade.

By default, gitlab-sshd listens for:

• External requests on port 22 (global.shell.port).
• Internal requests on port 2222 (gitlab.gitlab-shell.service.internalPort).

You can configure different ports in the Helm chart.

::EndTabs

PROXY protocol support

When a load balancer is used in front of gitlab-sshd, GitLab reports the IP address of the proxy instead of the actual IP address of the client. gitlab-sshd supports the PROXY protocol to obtain the real IP address.

::Tabs

:::TabTitle Linux package (Omnibus)

To enable the PROXY protocol:

1. Edit /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"
   

2. Save the file and reconfigure GitLab:

   sudo gitlab-ctl reconfigure
   

:::TabTitle Helm chart (Kubernetes)

1. Set the gitlab.gitlab-shell.config options. For example:

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

2. Perform a Helm upgrade.

::EndTabs