Merge branch '544-aqualls-recreate-sean-work' into 'main'

Incorporate older edits to README

Closes #544

See merge request https://gitlab.com/gitlab-org/gitlab-shell/-/merge_requests/696

Merged-by: Igor Drozdov <idrozdov@gitlab.com>
Approved-by: Jerry Seto <jseto@gitlab.com>
Approved-by: Igor Drozdov <idrozdov@gitlab.com>
Co-authored-by: Amy Qualls <aqualls@gitlab.com>

3 files changed, 103 insertions, 17 deletions

diff --git a/README.md b/README.md
index b3cbc01..add3d7f 100644
--- a/README.md
+++ b/README.md
@@ -6,41 +6,50 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 
 # GitLab Shell
 
-## GitLab Shell handles git SSH sessions for GitLab
+[![pipeline status](https://gitlab.com/gitlab-org/gitlab-shell/badges/main/pipeline.svg)](https://gitlab.com/gitlab-org/gitlab-shell/-/pipelines?ref=main)
+[![coverage report](https://gitlab.com/gitlab-org/gitlab-shell/badges/main/coverage.svg)](https://gitlab.com/gitlab-org/gitlab-shell/-/pipelines?ref=main)
+[![Code Climate](https://codeclimate.com/github/gitlabhq/gitlab-shell.svg)](https://codeclimate.com/github/gitlabhq/gitlab-shell)
 
 GitLab Shell handles git SSH sessions for GitLab and modifies the list of authorized keys.
 GitLab Shell is not a Unix shell nor a replacement for Bash or Zsh.
 
+GitLab supports Git LFS authentication through SSH.
+
+## Requirements
+
+GitLab Shell is written in Go, and needs a Go compiler to build. It still requires
+Ruby to build and test, but not to run.
+
+GitLab Shell runs on `port 22` on an Omnibus installation. To use a regular SSH
+service, configure it on an alternative port.
+
+Download and install the current version of Go from [golang.org](https://golang.org/dl/)
+We follow the [Golang Release Policy](https://golang.org/doc/devel/release.html#policy)
+of supporting the current stable version and the previous two major versions.
+
+## How GitLab Shell works
+
 When you access the GitLab server over SSH then GitLab Shell will:
 
-1. Limit you to predefined git commands (git push, git pull).
+1. Limit you to predefined git commands (`git push`, `git pull`, `git fetch`).
 1. Call the GitLab Rails API to check if you are authorized, and what Gitaly server your repository is on
 1. Copy data back and forth between the SSH client and the Gitaly server
 
 If you access a GitLab server over HTTP(S) you end up in [gitlab-workhorse](https://gitlab.com/gitlab-org/gitlab/tree/master/workhorse).
 
-An overview of the four cases described above:
+### `git pull` over SSH
 
 1. git pull over SSH -> gitlab-shell -> API call to gitlab-rails (Authorization) -> accept or decline -> establish Gitaly session
-1. git push over SSH -> gitlab-shell (git command is not executed yet) -> establish Gitaly session -> (in Gitaly) gitlab-shell pre-receive hook -> API call to gitlab-rails (authorization) -> accept or decline push
 
-[Full feature list](doc/features.md)
-
-## Code status
-
-[![pipeline status](https://gitlab.com/gitlab-org/gitlab-shell/badges/main/pipeline.svg)](https://gitlab.com/gitlab-org/gitlab-shell/-/pipelines?ref=main)
-[![coverage report](https://gitlab.com/gitlab-org/gitlab-shell/badges/main/coverage.svg)](https://gitlab.com/gitlab-org/gitlab-shell/-/pipelines?ref=main)
-[![Code Climate](https://codeclimate.com/github/gitlabhq/gitlab-shell.svg)](https://codeclimate.com/github/gitlabhq/gitlab-shell)
+### `git push` over SSH
 
-## Requirements
+1. git push over SSH -> gitlab-shell (git command is not executed yet) -> establish Gitaly session -> (in Gitaly) gitlab-shell pre-receive hook -> API call to gitlab-rails (authorization) -> accept or decline push
 
-GitLab Shell is written in Go, and needs a Go compiler to build. It still requires
-Ruby to build and test, but not to run.
+[Full feature list](doc/features.md)
 
-Download and install the current version of Go from https://golang.org/dl/
+### Modifies `authorized_keys`
 
-We follow the [Golang Release Policy](https://golang.org/doc/devel/release.html#policy)
-of supporting the current stable version and the previous two major versions.
+GitLab Shell modifies the `authorized_keys` file on the client machine.
 
 ## Rate Limiting
 
@@ -102,3 +111,7 @@ See [PROCESS.md](./PROCESS.md)
 ## License
 
 See [LICENSE](./LICENSE).
+
+## Related topics
+
+- [Using the GitLab Shell chart](https://docs.gitlab.com/charts/charts/gitlab/gitlab-shell/#using-the-gitlab-shell-chart)
diff --git a/doc/architecture.md b/doc/architecture.md
new file mode 100644
index 0000000..ff60273
--- /dev/null
+++ b/doc/architecture.md
@@ -0,0 +1,37 @@
+---
+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/engineering/ux/technical-writing/#assignments
+---
+
+# GitLab Shell architecture
+
+```mermaid
+sequenceDiagram
+    participant Git on client
+    participant SSH server
+    participant AuthorizedKeysCommand
+    participant GitLab Shell
+    participant Rails
+    participant Gitaly
+    participant Git on server
+
+    Note left of Git on client: git fetch
+    Git on client->>+SSH server: ssh git fetch-pack request
+    SSH server->>+AuthorizedKeysCommand: gitlab-shell-authorized-keys-check git AAAA...
+    AuthorizedKeysCommand->>+Rails: GET /internal/api/authorized_keys?key=AAAA...
+    Note right of Rails: Lookup key ID
+    Rails-->>-AuthorizedKeysCommand: 200 OK, command="gitlab-shell upload-pack key_id=1"
+    AuthorizedKeysCommand-->>-SSH server: command="gitlab-shell upload-pack key_id=1"
+    SSH server->>+GitLab Shell: gitlab-shell upload-pack key_id=1
+    GitLab Shell->>+Rails: GET /internal/api/allowed?action=upload_pack&key_id=1
+    Note right of Rails: Auth check
+    Rails-->>-GitLab Shell: 200 OK, { gitaly: ... }
+    GitLab Shell->>+Gitaly: SSHService.SSHUploadPack request
+    Gitaly->>+Git on server: git upload-pack request
+    Note over Git on client,Git on server: Bidirectional communication between Git client and server
+    Git on server-->>-Gitaly: git upload-pack response
+    Gitaly -->>-GitLab Shell: SSHService.SSHUploadPack response
+    GitLab Shell-->>-SSH server: gitlab-shell upload-pack response
+    SSH server-->>-Git on client: ssh git fetch-pack response
+```
diff --git a/doc/gitlab-sshd.md b/doc/gitlab-sshd.md
new file mode 100644
index 0000000..be97468
--- /dev/null
+++ b/doc/gitlab-sshd.md
@@ -0,0 +1,36 @@
+---
+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/engineering/ux/technical-writing/#assignments
+---
+
+# gitlab-sshd
+
+`gitlab-sshd` is a binary in [`gitlab-shell`](https://gitlab.com/gitlab-org/gitlab-shell)
+which runs as a persistent SSH daemon. It will replace `OpenSSH` on GitLab SaaS,
+and eventually other cloud-native environments. Instead of running an `sshd` process,
+we run a `gitlab-sshd` process that does the same job, in a more focused manner:
+
+```mermaid
+sequenceDiagram
+    participant Git on client
+    participant GitLab SSHD
+    participant Rails
+    participant Gitaly
+    participant Git on server
+
+    Note left of Git on client: git fetch
+    Git on client->>+GitLab SSHD: ssh git fetch-pack request
+    GitLab SSHD->>+Rails: GET /internal/api/authorized_keys?key=AAAA...
+    Note right of Rails: Lookup key ID
+    Rails-->>-GitLab SSHD: 200 OK, command="gitlab-shell upload-pack key_id=1"
+    GitLab SSHD->>+Rails: GET /internal/api/allowed?action=upload_pack&key_id=1
+    Note right of Rails: Auth check
+    Rails-->>-GitLab SSHD: 200 OK, { gitaly: ... }
+    GitLab SSHD->>+Gitaly: SSHService.SSHUploadPack request
+    Gitaly->>+Git on server: git upload-pack request
+    Note over Git on client,Git on server: Bidirectional communication between Git client and server
+    Git on server-->>-Gitaly: git upload-pack response
+    Gitaly -->>-GitLab SSHD: SSHService.SSHUploadPack response
+    GitLab SSHD-->>-Git on client: ssh git fetch-pack response
+```