`gitlab-sshd`

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

gitlab-sshd is a standalone SSH server written in Go. It is a lightweight alternative to OpenSSH. It is part of the gitlab-shell package and handles SSH operations.

While OpenSSH uses a restricted shell approach, gitlab-sshd:

Functions as a modern multi-threaded server application.
Uses Remote Procedure Calls (RPCs) instead of the SSH transport protocol.
Uses less memory than OpenSSH.
Supports group access restriction by IP address for applications running behind a proxy.

For more details about the implementation, see the blog post.

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

PROXY protocol: gitlab-sshd supports the PROXY protocol, allowing it to run behind proxy servers like HAProxy. This feature is not enabled by default but can be enabled.
SSH certificates: gitlab-sshd supports instance-level SSH certificate authentication by using trusted CA keys configured in config.yml. For more information, see Instance-level SSH certificates with gitlab-sshd.
2FA recovery codes: gitlab-sshd does not support 2FA recovery code regeneration. Attempting to run 2fa_recovery_codes results in the error: remote: ERROR: Unknown command: 2fa_recovery_codes. See the discussion for details.

The capabilities of GitLab Shell extend beyond Git operations and can be used for various SSH-based interactions with GitLab.

Enable `gitlab-sshd`

To use gitlab-sshd:

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

Edit /etc/gitlab/gitlab.rb:

ruby

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

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:
ruby
```
gitlab_sshd['generate_host_keys'] = false
```
Save the file and reconfigure GitLab:
shell
```
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.

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

Set the gitlab-shell charts sshDaemon option to gitlab-sshd. For example:
yaml
```
gitlab:
  gitlab-shell:
    sshDaemon: gitlab-sshd
```
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.

PROXY protocol support

Load balancers in front of gitlab-sshd cause GitLab to report the proxy IP address instead of the client IP address. To obtain the real IP address, gitlab-sshd supports the PROXY protocol.

To enable the PROXY protocol:

Edit /etc/gitlab/gitlab.rb:

ruby

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

For more information about the gitlab_sshd['proxy_policy'] options, see the go-proxyproto library.

Save the file and reconfigure GitLab:
shell
```
sudo gitlab-ctl reconfigure
```

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

yaml

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

Perform a Helm upgrade.

Enable gitlab-sshd

PROXY protocol support

Enable `gitlab-sshd`