diff options
author | GitLab Bot <gitlab-bot@gitlab.com> | 2023-02-09 06:07:46 +0300 |
---|---|---|
committer | GitLab Bot <gitlab-bot@gitlab.com> | 2023-02-09 06:07:46 +0300 |
commit | 38ff3a81189c8323d323946afcf7dad62c84b9aa (patch) | |
tree | f5763c753d647f63ec06daea3f83f2e0e6d5be4d /doc/administration/operations | |
parent | c46d8e7601c032d954c9f35761ae14dc4bacf6ce (diff) |
Add latest changes from gitlab-org/gitlab@master
Diffstat (limited to 'doc/administration/operations')
-rw-r--r-- | doc/administration/operations/fast_ssh_key_lookup.md | 157 | ||||
-rw-r--r-- | doc/administration/operations/gitlab_sshd.md | 139 | ||||
-rw-r--r-- | doc/administration/operations/index.md | 1 |
3 files changed, 159 insertions, 138 deletions
diff --git a/doc/administration/operations/fast_ssh_key_lookup.md b/doc/administration/operations/fast_ssh_key_lookup.md index b3cdbd05b29..4b7d7aaa479 100644 --- a/doc/administration/operations/fast_ssh_key_lookup.md +++ b/doc/administration/operations/fast_ssh_key_lookup.md @@ -25,10 +25,6 @@ GitLab Shell solves this by providing a way to authorize SSH users via a fast, indexed lookup in the GitLab database. This page describes how to enable the fast lookup of authorized SSH keys. -WARNING: -OpenSSH version 6.9+ is required because `AuthorizedKeysCommand` must be -able to accept a fingerprint. Check the version of OpenSSH on your server with `sshd -V`. - ## Fast lookup is required for Geo **(PREMIUM)** Unlike [Cloud Native GitLab](https://docs.gitlab.com/charts/), Omnibus GitLab by default @@ -51,12 +47,29 @@ secondary nodes, but **Write to "authorized keys" file** must be unchecked only on the primary node, because it is reflected automatically on the secondary if database replication is working. -## Setting up fast lookup via GitLab Shell +## Set up fast lookup GitLab Shell provides a way to authorize SSH users via a fast, indexed lookup to the GitLab database. GitLab Shell uses the fingerprint of the SSH key to check whether the user is authorized to access GitLab. +Fast lookup can be enabled with the following SSH servers: + +- [`gitlab-sshd`](gitlab_sshd.md) +- OpenSSH + +### `gitlab-sshd` + +To set up `gitlab-sshd`, see [the `gitlab-sshd` documentation](gitlab_sshd.md). +After `gitlab-sshd` is enabled, GitLab Shell and `gitlab-sshd` are configured +to use fast lookup automatically. + +### OpenSSH + +WARNING: +OpenSSH version 6.9+ is required because `AuthorizedKeysCommand` must be +able to accept a fingerprint. Check the version of OpenSSH on your server with `sshd -V`. + Add the following to your `sshd_config` file. This file is usually located at `/etc/ssh/sshd_config`, but it is at `/assets/sshd_config` if you're using Omnibus Docker: @@ -119,7 +132,7 @@ Then you can backup and delete your `authorized_keys` file for best performance. The current users' keys are already present in the database, so there is no need for migration or for users to re-add their keys. -## How to go back to using the `authorized_keys` file +### How to go back to using the `authorized_keys` file This overview is brief. Refer to the above instructions for more context. @@ -132,138 +145,6 @@ This overview is brief. Refer to the above instructions for more context. 1. Remove the `AuthorizedKeysCommand` lines from `/etc/ssh/sshd_config` or from `/assets/sshd_config` if you are using Omnibus Docker. 1. Reload `sshd`: `sudo service sshd reload`. -## Use `gitlab-sshd` instead of OpenSSH - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/299109) in GitLab 14.5 as an **Alpha** release for self-managed customers. -> - Ready for production use with [Cloud Native GitLab in GitLab 15.1](https://gitlab.com/gitlab-org/charts/gitlab/-/issues/2540) and [Omnibus GitLab in GitLab 15.9](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/5937). - -`gitlab-sshd` is [a standalone SSH server](https://gitlab.com/gitlab-org/gitlab-shell/-/tree/main/internal/sshd) -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](../../user/group/index.md) for applications -running behind the proxy. - -`gitlab-sshd` is a lightweight alternative to OpenSSH for providing -[SSH operations](https://gitlab.com/gitlab-org/gitlab-shell/-/blob/71a7f34a476f778e62f8fe7a453d632d395eaf8f/doc/features.md). -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](https://about.gitlab.com/blog/2022/08/17/why-we-have-implemented-our-own-sshd-solution-on-gitlab-sass/) 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](#proxy-protocol-support). -- `gitlab-sshd` **does not** support SSH certificates. For more details, read - [issue #495](https://gitlab.com/gitlab-org/gitlab-shell/-/issues/495). - -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`: - - ```ruby - gitlab_sshd['enable'] = true - gitlab_sshd['listen_address'] = '[::]:2222' # Adjust the port accordingly - ``` - -1. 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: - - ```ruby - gitlab_sshd['generate_host_keys'] = false - ``` - -1. 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. - -:::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`](https://docs.gitlab.com/charts/charts/gitlab/gitlab-shell/index.html#installation-command-line-options). - For example: - - ```yaml - gitlab: - gitlab-shell: - sshDaemon: gitlab-sshd - ``` - -1. 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](https://docs.gitlab.com/charts/charts/gitlab/gitlab-shell/#configuration). - -::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](https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt) to -obtain the real IP address. - -::Tabs - -:::TabTitle Linux package (Omnibus) - -To enable the PROXY protocol: - -1. 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" - ``` - -1. Save the file and reconfigure GitLab: - - ```shell - sudo gitlab-ctl reconfigure - ``` - -:::TabTitle Helm chart (Kubernetes) - -1. Set the [`gitlab.gitlab-shell.config` options](https://docs.gitlab.com/charts/charts/gitlab/gitlab-shell/index.html#installation-command-line-options). For example: - - ```yaml - gitlab: - gitlab-shell: - config: - proxyProtocol: true - proxyPolicy: "use" - ``` - -1. Perform a Helm upgrade. - -::EndTabs - ## SELinux support and limitations GitLab supports `authorized_keys` database lookups with [SELinux](https://en.wikipedia.org/wiki/Security-Enhanced_Linux). diff --git a/doc/administration/operations/gitlab_sshd.md b/doc/administration/operations/gitlab_sshd.md new file mode 100644 index 00000000000..7b61631fe3a --- /dev/null +++ b/doc/administration/operations/gitlab_sshd.md @@ -0,0 +1,139 @@ +--- +stage: Create +group: Source Code +info: 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](https://gitlab.com/gitlab-org/gitlab/-/issues/299109) in GitLab 14.5 as an **Alpha** release for self-managed customers. +> - Ready for production use with [Cloud Native GitLab in GitLab 15.1](https://gitlab.com/gitlab-org/charts/gitlab/-/issues/2540) and [Omnibus GitLab in GitLab 15.9](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/5937). + +`gitlab-sshd` is [a standalone SSH server](https://gitlab.com/gitlab-org/gitlab-shell/-/tree/main/internal/sshd) +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](../../user/group/index.md) for applications +running behind the proxy. + +`gitlab-sshd` is a lightweight alternative to OpenSSH for providing +[SSH operations](https://gitlab.com/gitlab-org/gitlab-shell/-/blob/71a7f34a476f778e62f8fe7a453d632d395eaf8f/doc/features.md). +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](https://about.gitlab.com/blog/2022/08/17/why-we-have-implemented-our-own-sshd-solution-on-gitlab-sass/) 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](#proxy-protocol-support). +- `gitlab-sshd` **does not** support SSH certificates. For more details, read + [issue #495](https://gitlab.com/gitlab-org/gitlab-shell/-/issues/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`: + + ```ruby + gitlab_sshd['enable'] = true + gitlab_sshd['listen_address'] = '[::]:2222' # Adjust the port accordingly + ``` + +1. 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: + + ```ruby + gitlab_sshd['generate_host_keys'] = false + ``` + +1. 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. + +:::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`](https://docs.gitlab.com/charts/charts/gitlab/gitlab-shell/index.html#installation-command-line-options). + For example: + + ```yaml + gitlab: + gitlab-shell: + sshDaemon: gitlab-sshd + ``` + +1. 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](https://docs.gitlab.com/charts/charts/gitlab/gitlab-shell/#configuration). + +::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](https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt) to +obtain the real IP address. + +::Tabs + +:::TabTitle Linux package (Omnibus) + +To enable the PROXY protocol: + +1. 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" + ``` + +1. Save the file and reconfigure GitLab: + + ```shell + sudo gitlab-ctl reconfigure + ``` + +:::TabTitle Helm chart (Kubernetes) + +1. Set the [`gitlab.gitlab-shell.config` options](https://docs.gitlab.com/charts/charts/gitlab/gitlab-shell/index.html#installation-command-line-options). For example: + + ```yaml + gitlab: + gitlab-shell: + config: + proxyProtocol: true + proxyPolicy: "use" + ``` + +1. Perform a Helm upgrade. + +::EndTabs diff --git a/doc/administration/operations/index.md b/doc/administration/operations/index.md index 527a72c5933..f6ab46b9fbf 100644 --- a/doc/administration/operations/index.md +++ b/doc/administration/operations/index.md @@ -17,6 +17,7 @@ Keep your GitLab instance up and running smoothly. to restart Sidekiq. - [Multiple Sidekiq processes](../sidekiq/extra_sidekiq_processes.md): Configure multiple Sidekiq processes to ensure certain queues always have dedicated workers, no matter the number of jobs that must be processed. **(FREE SELF)** - [Puma](puma.md): Understand Puma and puma-worker-killer. +- [`gitlab-sshd`](gitlab_sshd.md): Use GitLab SSH daemon instead of OpenSSH. - Speed up SSH operations by [Authorizing SSH users via a fast, indexed lookup to the GitLab database](fast_ssh_key_lookup.md), and/or by [doing away with user SSH keys stored on GitLab entirely in favor of SSH certificates](ssh_certificates.md). |