gitlab-sshd All tiers Self-managed

Version history

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 discussion about adding them, see issue 655.

Enable gitlab-sshd

To use gitlab-sshd:

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, Linux package installations generate 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.

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.

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