Add latest changes from gitlab-org/gitlab@15-9-stable-eev15.9.0-rc42

7 files changed, 175 insertions, 64 deletions

diff --git a/doc/administration/operations/fast_ssh_key_lookup.md b/doc/administration/operations/fast_ssh_key_lookup.md
index a34b21e676a..1e887d8bd67 100644
--- a/doc/administration/operations/fast_ssh_key_lookup.md
+++ b/doc/administration/operations/fast_ssh_key_lookup.md
@@ -8,7 +8,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 
 NOTE:
 This document describes a drop-in replacement for the
-`authorized_keys` file. For normal (non-deploy key) users, consider using
+`authorized_keys` file. For standard (non-deploy key) users, consider using
 [SSH certificates](ssh_certificates.md). They are even faster, but are not a
 drop-in replacement.
 
@@ -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,31 @@ 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
+
+You can run both services simultaneously by using separate ports for each service.
+
+### With `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.
+
+### With 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 +134,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,52 +147,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.
-
-WARNING:
-`gitlab-sshd` is in [**Alpha**](../../policy/alpha-beta-support.md#alpha-features).
-It is not ready for production use.
-
-`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).
-
-The capabilities of GitLab Shell are not limited to Git operations.
-
-If you are considering switching from OpenSSH to `gitlab-sshd`, consider these concerns:
-
-- The `gitlab-sshd` component is only available for
-  [GitLab Helm chart](https://docs.gitlab.com/charts/) deployments.
-- `gitlab-sshd` supports the PROXY protocol. It can run behind proxy servers that rely
-  on it, such as HAProxy. The PROXY protocol not enabled by default, but can be enabled with a Helm chart setting.
-- By default, `gitlab-sshd` binds to port 22, but you can configure a different port in the Helm chart.
-- `gitlab-sshd` **does not** support SSH certificates. For more details, read
-  [issue #495](https://gitlab.com/gitlab-org/gitlab-shell/-/issues/495).
-
-To switch from OpenSSH to `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.
-
 ## 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).
diff --git a/doc/administration/operations/moving_repositories.md b/doc/administration/operations/moving_repositories.md
index 5066f6d99d8..aa0477be788 100644
--- a/doc/administration/operations/moving_repositories.md
+++ b/doc/administration/operations/moving_repositories.md
@@ -65,6 +65,8 @@ To move repositories:
      [individual snippets](../../api/snippet_repository_storage_moves.md#schedule-a-repository-storage-move-for-a-snippet).
    - [All groups](#move-all-groups) or
      [individual groups](../../api/group_repository_storage_moves.md#schedule-a-repository-storage-move-for-a-group). **(PREMIUM SELF)**
+1. If [Geo](../geo/index.md) is enabled,
+   [resync all repositories](../geo/replication/troubleshooting.md#queue-up-all-repositories-for-resync).
 
 #### Move all projects
 
diff --git a/doc/administration/operations/puma.md b/doc/administration/operations/puma.md
index 51d6e9ae1fd..f2f9f1cdcda 100644
--- a/doc/administration/operations/puma.md
+++ b/doc/administration/operations/puma.md
@@ -138,7 +138,7 @@ When running Puma in single mode, some features are not supported:
 - [Phased restart](https://gitlab.com/gitlab-org/gitlab/-/issues/300665)
 - [Memory killers](#reducing-memory-use)
 
-To learn more, visit [epic 5303](https://gitlab.com/groups/gitlab-org/-/epics/5303).
+For more information, see [epic 5303](https://gitlab.com/groups/gitlab-org/-/epics/5303).
 
 ## Performance caveat when using Puma with Rugged
 
@@ -223,7 +223,7 @@ from the Linux package and is no longer supported.
 
 Puma has a multi-thread architecture that uses less memory than a multi-process
 application server like Unicorn. On GitLab.com, we saw a 40% reduction in memory
-consumption. Most Rails application requests normally include a proportion of I/O wait time.
+consumption. Most Rails application requests usually include a proportion of I/O wait time.
 
 During I/O wait time, MRI Ruby releases the GVL to other threads.
 Multi-threaded Puma can therefore still serve more requests than a single process.
diff --git a/doc/administration/operations/rails_console.md b/doc/administration/operations/rails_console.md
index f2143435755..652a4fa5497 100644
--- a/doc/administration/operations/rails_console.md
+++ b/doc/administration/operations/rails_console.md
@@ -158,7 +158,7 @@ sudo -u git -H bundle exec rails runner -e production /path/to/script.rb
 
 Rails Runner does not produce the same output as the console.
 
-If you set a variable on the console, the console will generate useful debug output
+If you set a variable on the console, the console generates useful debug output
 such as the variable contents or properties of referenced entity:
 
 ```ruby
@@ -176,7 +176,7 @@ root
 1
 ```
 
-Some basic knowledge of Ruby will be very useful. Try
+Some basic knowledge of Ruby is very useful. Try
 [this 30-minute tutorial](https://try.ruby-lang.org/) for a quick introduction.
 Rails experience is helpful but not essential.
 
@@ -425,7 +425,7 @@ D, [2020-03-05T17:18:30.406047 #910] DEBUG -- :   User Load (2.6ms)  SELECT "use
 ```
 
 For more on different ways to retrieve data from the database using Active
-Record, please see the [Active Record Query Interface documentation](https://guides.rubyonrails.org/active_record_querying.html).
+Record, see the [Active Record Query Interface documentation](https://guides.rubyonrails.org/active_record_querying.html).
 
 ## Query the database using an Active Record model
 
@@ -547,7 +547,7 @@ be the fastest way to get to the root of the problem.
 
 ### Interacting with Active Record objects
 
-At the end of the day, Active Record objects are just normal Ruby objects. As
+At the end of the day, Active Record objects are just standard Ruby objects. As
 such, we can define methods on them which perform arbitrary actions.
 
 For example, GitLab developers have added some methods which help with
diff --git a/doc/administration/operations/ssh_certificates.md b/doc/administration/operations/ssh_certificates.md
index 401451d58b4..bdd1045f7a7 100644
--- a/doc/administration/operations/ssh_certificates.md
+++ b/doc/administration/operations/ssh_certificates.md
@@ -74,7 +74,7 @@ $ ssh-add -L | grep cert | ssh-keygen -L -f -
 ```
 
 Technically that's not strictly true, for example, it could be
-`prod-aearnfjord` if it's a SSH certificate you'd normally sign in to
+`prod-aearnfjord` if it's a SSH certificate you'd usually sign in to
 servers as the `prod-aearnfjord` user, but then you must specify your
 own `AuthorizedPrincipalsCommand` to do that mapping instead of using
 our provided default.
@@ -122,7 +122,7 @@ You can supply as many principals as you want, these are turned
 into multiple lines of `authorized_keys` output, as described in the
 `AuthorizedPrincipalsFile` documentation in `sshd_config(5)`.
 
-Normally when using the `AuthorizedKeysCommand` with OpenSSH the
+Usually when using the `AuthorizedKeysCommand` with OpenSSH the
 principal is some "group" that's allowed to sign in to that
 server. However with GitLab it's only used to appease OpenSSH's
 requirement for it, we effectively only care about the "key ID" being
@@ -145,13 +145,13 @@ authenticate the user, OpenSSH falls back on
 
 Therefore there may still be a reason to use the [Fast lookup of authorized SSH keys in the database](fast_ssh_key_lookup.md) method
 in conjunction with this. Since you are using SSH certificates for
-all your normal users, and relying on the `~/.ssh/authorized_keys`
+all your typical users, and relying on the `~/.ssh/authorized_keys`
 fallback for deploy keys, if you make use of those.
 
 But you may find that there's no reason to do that, since all your
-normal users use the fast `AuthorizedPrincipalsCommand` path, and
+typical users use the fast `AuthorizedPrincipalsCommand` path, and
 only automated deployment key access falls back on
-`~/.ssh/authorized_keys`, or that you have a lot more keys for normal
+`~/.ssh/authorized_keys`, or that you have a lot more keys for typical
 users (especially if they're renewed) than you have deploy keys.
 
 ## Other security caveats