diff --git a/doc/topics/git/troubleshooting_git.md b/doc/topics/git/troubleshooting_git.md index c9eb72a9d8c3ebe6e03d3405f5537bfccd5bea51..1f424aba00ac514b6182e964ae53b4d8ebb8f1ce 100644 --- a/doc/topics/git/troubleshooting_git.md +++ b/doc/topics/git/troubleshooting_git.md @@ -92,7 +92,7 @@ If neither approach fixes the error, you may need a different internet service p **If pushing over SSH**, first check your SSH configuration as 'Broken pipe' errors can sometimes be caused by underlying issues with SSH (such as authentication). Make sure that SSH is correctly configured by following the -instructions in the [SSH troubleshooting](../../user/ssh.md#password-prompt-with-git-clone) documentation. +instructions in the [SSH troubleshooting](../../user/ssh_troubleshooting.md#password-prompt-with-git-clone) documentation. If you're a GitLab administrator with server access, you can also prevent session timeouts by configuring SSH `keep-alive` on the client or the server. diff --git a/doc/user/ssh.md b/doc/user/ssh.md index f8ad75d3c1375c23fee8d915933c17730482b841..fbd618da4938d1f2b6d9ca2df29d7dab54c86041 100644 --- a/doc/user/ssh.md +++ b/doc/user/ssh.md @@ -80,7 +80,7 @@ Available documentation suggests ED25519 is more secure than RSA. If you use an RSA key, the US National Institute of Standards and Technology in [Publication 800-57 Part 3 (PDF)](https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-57Pt3r1.pdf) recommends a key size of at least 2048 bits. Due to limitations in Go, -RSA keys [cannot exceed 8192 bits](#tls-server-sent-certificate-containing-rsa-key-larger-than-8192-bits). +RSA keys [cannot exceed 8192 bits](ssh_troubleshooting.md#tls-server-sent-certificate-containing-rsa-key-larger-than-8192-bits). The default key size depends on your version of `ssh-keygen`. Review the `man` page for your installed `ssh-keygen` command for details. @@ -559,68 +559,3 @@ chmod 700 /var/opt/gitlab/.ssh/ chmod 600 /var/opt/gitlab/.ssh/authorized_keys chmod 644 /var/opt/gitlab/.ssh/authorized_keys.lock ``` - -## Troubleshooting - -### TLS: server sent certificate containing RSA key larger than 8192 bits - -In GitLab 16.3 and later, Go limits RSA keys to a maximum of 8192 bits. -To check the length of a key: - -```shell -openssl rsa -in <your-key-file> -text -noout | grep "Key:" -``` - -Replace any key longer than 8192 bits with a shorter key. - -### Password prompt with `git clone` - -When you run `git clone`, you may be prompted for a password, like `git@gitlab.example.com's password:`. -This indicates that something is wrong with your SSH setup. - -- Ensure that you generated your SSH key pair correctly and added the public SSH - key to your GitLab profile. -- Try to manually register your private SSH key by using `ssh-agent`. -- Try to debug the connection by running `ssh -Tv git@example.com`. - Replace `example.com` with your GitLab URL. -- Ensure you followed all the instructions in [Use SSH on Microsoft Windows](#use-ssh-on-microsoft-windows). -- Ensure that you have [Verify GitLab SSH ownership and permissions](#verify-gitlab-ssh-ownership-and-permissions). If you have several hosts ensure that permissions are correct in all hosts. - -### `Could not resolve hostname` error - -You may receive the following error when [verifying that you can connect](#verify-that-you-can-connect): - -```shell -ssh: Could not resolve hostname gitlab.example.com: nodename nor servname provided, or not known -``` - -If you receive this error, restart your terminal and try the command again. - -### `Key enrollment failed: invalid format` error - -You may receive the following error when [generating an SSH key pair for a FIDO2 hardware security key](#generate-an-ssh-key-pair-for-a-fido2-hardware-security-key): - -```shell -Key enrollment failed: invalid format -``` - -You can troubleshoot this by trying the following: - -- Run the `ssh-keygen` command using `sudo`. -- Verify your FIDO2 hardware security key supports - the key type provided. -- Verify the version of OpenSSH is 8.2 or greater by - running `ssh -V`. - -### Error: `SSH host keys are not available on this system.` - -If GitLab does not have access to the host SSH keys, when you visit `gitlab.example/help/instance_configuration`, you see the following error message under the **SSH host key fingerprints** header instead of the instance SSH fingerprint: - -```plaintext -SSH host keys are not available on this system. Please use ssh-keyscan command or contact your GitLab administrator for more information. -``` - -To resolve this error: - -- On Helm chart (Kubernetes) deployments, update the `values.yaml` to set [`sshHostKeys.mount`](https://docs.gitlab.com/charts/charts/gitlab/webservice/) to `true` under the `webservice` section. -- On GitLab self-managed installations, check the `/etc/ssh` directory for the host keys. diff --git a/doc/user/ssh_troubleshooting.md b/doc/user/ssh_troubleshooting.md new file mode 100644 index 0000000000000000000000000000000000000000..0e0e5d89e60646d36f1b621b05746434076cc57e --- /dev/null +++ b/doc/user/ssh_troubleshooting.md @@ -0,0 +1,72 @@ +--- +stage: Govern +group: Authentication +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Troubleshooting SSH + +When working with SSH keys, you might encounter the following issues. + +## TLS: server sent certificate containing RSA key larger than 8192 bits + +In GitLab 16.3 and later, Go limits RSA keys to a maximum of 8192 bits. +To check the length of a key: + +```shell +openssl rsa -in <your-key-file> -text -noout | grep "Key:" +``` + +Replace any key longer than 8192 bits with a shorter key. + +## Password prompt with `git clone` + +When you run `git clone`, you may be prompted for a password, like `git@gitlab.example.com's password:`. +This indicates that something is wrong with your SSH setup. + +- Ensure that you generated your SSH key pair correctly and added the public SSH + key to your GitLab profile. +- Try to manually register your private SSH key by using `ssh-agent`. +- Try to debug the connection by running `ssh -Tv git@example.com`. + Replace `example.com` with your GitLab URL. +- Ensure you followed all the instructions in [Use SSH on Microsoft Windows](ssh.md#use-ssh-on-microsoft-windows). +- Ensure that you have [Verify GitLab SSH ownership and permissions](ssh.md#verify-gitlab-ssh-ownership-and-permissions). If you have several hosts ensure that permissions are correct in all hosts. + +## `Could not resolve hostname` error + +You may receive the following error when [verifying that you can connect](ssh.md#verify-that-you-can-connect): + +```shell +ssh: Could not resolve hostname gitlab.example.com: nodename nor servname provided, or not known +``` + +If you receive this error, restart your terminal and try the command again. + +### `Key enrollment failed: invalid format` error + +You may receive the following error when [generating an SSH key pair for a FIDO2 hardware security key](ssh.md#generate-an-ssh-key-pair-for-a-fido2-hardware-security-key): + +```shell +Key enrollment failed: invalid format +``` + +You can troubleshoot this by trying the following: + +- Run the `ssh-keygen` command using `sudo`. +- Verify your FIDO2 hardware security key supports + the key type provided. +- Verify the version of OpenSSH is 8.2 or greater by + running `ssh -V`. + +## Error: `SSH host keys are not available on this system.` + +If GitLab does not have access to the host SSH keys, when you visit `gitlab.example/help/instance_configuration`, you see the following error message under the **SSH host key fingerprints** header instead of the instance SSH fingerprint: + +```plaintext +SSH host keys are not available on this system. Please use ssh-keyscan command or contact your GitLab administrator for more information. +``` + +To resolve this error: + +- On Helm chart (Kubernetes) deployments, update the `values.yaml` to set [`sshHostKeys.mount`](https://docs.gitlab.com/charts/charts/gitlab/webservice/) to `true` under the `webservice` section. +- On GitLab self-managed installations, check the `/etc/ssh` directory for the host keys.