gitlab-sshd
- Tier: Free, Premium, Ultimate
- Offering: GitLab Self-Managed
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.gitlab-sshd
does not support 2FA recovery code regeneration. Attempting to run2fa_recovery_codes
results in the following error:remote: ERROR: Unknown command: 2fa_recovery_codes
. See the discussion for more information.
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"
For more information about the
gitlab_sshd['proxy_policy']
options, see thego-proxyproto
library.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.
Docs
Edit this page to fix an error or add an improvement in a merge request.
Create an issue to suggest an improvement to this page.
Product
Create an issue if there's something you don't like about this feature.
Propose functionality by submitting a feature request.
Feature availability and product trials
View pricing to see all GitLab tiers and features, or to upgrade.
Try GitLab for free with access to all features for 30 days.
Get help
If you didn't find what you were looking for, search the docs.
If you want help with something specific and could use community support, post on the GitLab forum.
For problems setting up or using this feature (depending on your GitLab subscription).
Request support