gitlab-sshd
Offering: Self-managed
- Introduced in GitLab 14.5 as an Experiment for self-managed customers.
- Ready for production use with Cloud Native GitLab in GitLab 15.1 and Linux packages 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 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:
-
Edit
/etc/gitlab/gitlab.rb
: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:gitlab_sshd['generate_host_keys'] = false
-
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.
The following instructions switch OpenSSH in favor of gitlab-sshd
:
-
Set the
gitlab-shell
chartssshDaemon
option togitlab-sshd
. For example: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
).
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:
-
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"
-
Save the file and reconfigure GitLab:
sudo gitlab-ctl reconfigure
-
Set the
gitlab.gitlab-shell.config
options. For example:gitlab: gitlab-shell: config: proxyProtocol: true proxyPolicy: "use"
-
Perform a Helm upgrade.