diff options
Diffstat (limited to 'doc/administration/troubleshooting/ssl.md')
| -rw-r--r-- | doc/administration/troubleshooting/ssl.md | 111 |
1 files changed, 69 insertions, 42 deletions
diff --git a/doc/administration/troubleshooting/ssl.md b/doc/administration/troubleshooting/ssl.md index 996856521b7..d7bfd537eca 100644 --- a/doc/administration/troubleshooting/ssl.md +++ b/doc/administration/troubleshooting/ssl.md @@ -1,32 +1,36 @@ --- -stage: none -group: unassigned -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/#designated-technical-writers +stage: Enablement +group: Distribution +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 type: reference --- # Troubleshooting SSL -This page contains a list of common SSL-related errors and scenarios that you may face while working with GitLab. -It should serve as an addition to the main SSL docs available here: +This page contains a list of common SSL-related errors and scenarios that you +may encounter while working with GitLab. It should serve as an addition to the +main SSL docs available here: -- [Omnibus SSL Configuration](https://docs.gitlab.com/omnibus/settings/ssl.html) -- [Self-signed certificates or custom Certification Authorities for GitLab Runner](https://docs.gitlab.com/runner/configuration/tls-self-signed.html) -- [Manually configuring HTTPS](https://docs.gitlab.com/omnibus/settings/nginx.html#manually-configuring-https) +- [Omnibus SSL Configuration](https://docs.gitlab.com/omnibus/settings/ssl.html). +- [Self-signed certificates or custom Certification Authorities for GitLab Runner](https://docs.gitlab.com/runner/configuration/tls-self-signed.html). +- [Manually configuring HTTPS](https://docs.gitlab.com/omnibus/settings/nginx.html#manually-configuring-https). ## Using an internal CA certificate with GitLab -After configuring a GitLab instance with an internal CA certificate, you might not be able to access it via various CLI tools. You may see the following symptoms: +After configuring a GitLab instance with an internal CA certificate, you might +not be able to access it by using various CLI tools. You may see experience the +following issues: - `curl` fails: ```shell - curl https://gitlab.domain.tld + curl "https://gitlab.domain.tld" curl: (60) SSL certificate problem: unable to get local issuer certificate More details here: https://curl.haxx.se/docs/sslcerts.html ``` -- Testing via the [rails console](../operations/rails_console.md#starting-a-rails-console-session) also fails: +- Testing by using the [rails console](../operations/rails_console.md#starting-a-rails-console-session) + also fails: ```ruby uri = URI.parse("https://gitlab.domain.tld") @@ -40,33 +44,36 @@ After configuring a GitLab instance with an internal CA certificate, you might n OpenSSL::SSL::SSLError (SSL_connect returned=1 errno=0 state=error: certificate verify failed (unable to get local issuer certificate)) ``` -- The error `SSL certificate problem: unable to get local issuer certificate` is shown when setting up a [mirror](../../user/project/repository/repository_mirroring.md#repository-mirroring) from this GitLab instance. +- The error `SSL certificate problem: unable to get local issuer certificate` + is displayed when setting up a [mirror](../../user/project/repository/repository_mirroring.md#repository-mirroring) + from this GitLab instance. - `openssl` works when specifying the path to the certificate: ```shell /opt/gitlab/embedded/bin/openssl s_client -CAfile /root/my-cert.crt -connect gitlab.domain.tld:443 ``` -If you have the problems listed above, add your certificate to `/etc/gitlab/trusted-certs` and run `sudo gitlab-ctl reconfigure`. +If you have the previously described issues, add your certificate to +`/etc/gitlab/trusted-certs`, and then run `sudo gitlab-ctl reconfigure`. ## X.509 key values mismatch error -After configuring your instance with a certificate bundle, NGINX may throw the -following error: +After configuring your instance with a certificate bundle, NGINX may display +the following error message: `SSL: error:0B080074:x509 certificate routines:X509_check_private_key:key values mismatch` -This error means that the server certificate and key you have provided do not -match. You can confirm this by running the following command and comparing the -output: +This error message means that the server certificate and key you have provided +don't match. You can confirm this by running the following command and then +comparing the output: ```shell openssl rsa -noout -modulus -in path/to/your/.key | openssl md5 openssl x509 -noout -modulus -in path/to/your/.crt | openssl md5 ``` -The following is an example of an md5 output between a matching key and certificate. Note the -matching md5 hashes: +The following is an example of an md5 output between a matching key and +certificate. Note the matching md5 hashes: ```shell $ openssl rsa -noout -modulus -in private.key | openssl md5 @@ -75,7 +82,8 @@ $ openssl x509 -noout -modulus -in public.crt | openssl md5 4f49b61b25225abeb7542b29ae20e98c ``` -This is an opposing output with a non-matching key and certificate which shows different md5 hashes: +This is an opposing output with a non-matching key and certificate which shows +different md5 hashes: ```shell $ openssl rsa -noout -modulus -in private.key | openssl md5 @@ -84,14 +92,16 @@ $ openssl x509 -noout -modulus -in public.crt | openssl md5 4f49b61b25225abeb7542b29ae20e98c ``` -If the two outputs differ like the above example, there is a mismatch between the certificate -and key. You should contact the provider of the SSL certificate for further support. +If the two outputs differ like the previous example, there's a mismatch between +the certificate and key. Contact the provider of the SSL certificate for +further support. ## Using GitLab Runner with a GitLab instance configured with internal CA certificate or self-signed certificate Besides getting the errors mentioned in [Using an internal CA certificate with GitLab](ssl.md#using-an-internal-ca-certificate-with-gitlab), -your CI pipelines may get stuck in `Pending` status. In the runner logs you may see the below error: +your CI pipelines may get stuck in `Pending` status. In the runner logs you may +see the following error message: ```shell Dec 6 02:43:17 runner-host01 gitlab-runner[15131]: #033[0;33mWARNING: Checking for jobs... failed @@ -100,23 +110,27 @@ https://gitlab.domain.tld/api/v4/jobs/request: Post https://gitlab.domain.tld/ap x509: certificate signed by unknown authority ``` -If you face similar problem, add your certificate to `/etc/gitlab-runner/certs` and restart the runner via `gitlab-runner restart`. +If you encounter a similar problem, add your certificate to `/etc/gitlab-runner/certs`, +and the restart the runner by running `gitlab-runner restart`. ## Mirroring a remote GitLab repository that uses a self-signed SSL certificate -**Scenario:** When configuring a local GitLab instance to [mirror a repository](../../user/project/repository/repository_mirroring.md) from a remote GitLab instance that uses a self-signed certificate, you may see the `SSL certificate problem: self signed certificate` error in the UI. +When configuring a local GitLab instance to [mirror a repository](../../user/project/repository/repository_mirroring.md) +from a remote GitLab instance that uses a self-signed certificate, you may see +the `SSL certificate problem: self signed certificate` error message in the +user interface. The cause of the issue can be confirmed by checking if: - `curl` fails: ```shell - $ curl https://gitlab.domain.tld + $ curl "https://gitlab.domain.tld" curl: (60) SSL certificate problem: self signed certificate More details here: https://curl.haxx.se/docs/sslcerts.html ``` -- Testing via the Rails console also fails: +- Testing by using the Rails console also fails: ```ruby uri = URI.parse("https://gitlab.domain.tld") @@ -132,10 +146,15 @@ The cause of the issue can be confirmed by checking if: To fix this problem: -- Add the self-signed certificate from the remote GitLab instance to the `/etc/gitlab/trusted-certs` directory on the local GitLab instance and run `sudo gitlab-ctl reconfigure` as per the instructions for [installing custom public certificates](https://docs.gitlab.com/omnibus/settings/ssl.html#install-custom-public-certificates). -- If your local GitLab instance was installed using the Helm Charts, you can [add your self-signed certificate to your GitLab instance](https://docs.gitlab.com/runner/install/kubernetes.html#providing-a-custom-certificate-for-accessing-gitlab). +- Add the self-signed certificate from the remote GitLab instance to the + `/etc/gitlab/trusted-certs` directory on the local GitLab instance, and then + run `sudo gitlab-ctl reconfigure` as per the instructions for + [installing custom public certificates](https://docs.gitlab.com/omnibus/settings/ssl.html#install-custom-public-certificates). +- If your local GitLab instance was installed using the Helm Charts, you can + [add your self-signed certificate to your GitLab instance](https://docs.gitlab.com/runner/install/kubernetes.html#providing-a-custom-certificate-for-accessing-gitlab). -You may also get another error when trying to mirror a repository from a remote GitLab instance that uses a self-signed certificate: +You may also get another error message when trying to mirror a repository from +a remote GitLab instance that uses a self-signed certificate: ```shell 2:Fetching remote upstream failed: fatal: unable to access 'https://gitlab.domain.tld/root/test-repo/': @@ -144,12 +163,16 @@ SSL: unable to obtain common name from peer certificate In this case, the problem can be related to the certificate itself: -- Double check that your self-signed certificate is not missing a common name. If it is then regenerate a valid certificate -- add it to `/etc/gitlab/trusted-certs` and run `sudo gitlab-ctl reconfigure` +1. Validate that your self-signed certificate isn't missing a common name. If it + is, regenerate a valid certificate +1. Add the certificate to `/etc/gitlab/trusted-certs`. +1. Run `sudo gitlab-ctl reconfigure`. ## Unable to perform Git operations due to an internal or self-signed certificate -If your GitLab instance is using a self-signed certificate, or the certificate is signed by an internal certificate authority (CA), you might run into the following errors when attempting to perform Git operations: +If your GitLab instance is using a self-signed certificate, or if the +certificate is signed by an internal certificate authority (CA), you might +experience the following errors when attempting to perform Git operations: ```shell $ git clone https://gitlab.domain.tld/group/project.git @@ -165,15 +188,19 @@ fatal: unable to access 'https://gitlab.domain.tld/group/project.git/': server c To fix this problem: -- If possible, use SSH remotes for all Git operations. This is considered more secure and convenient to use. +- If possible, use SSH remotes for all Git operations. This is considered more + secure and convenient to use. - If you must use HTTPS remotes, you can try the following: - - Copy the self signed certificate or the internal root CA certificate to a local directory (for example, `~/.ssl`) and configure Git to trust your certificate: + - Copy the self-signed certificate or the internal root CA certificate to a + local directory (for example, `~/.ssl`) and configure Git to trust your + certificate: ```shell git config --global http.sslCAInfo ~/.ssl/gitlab.domain.tld.crt ``` - - Disable SSL verification in your Git client. Note that this intended as a temporary measure as it could be considered a **security risk**. + - Disable SSL verification in your Git client. Note that this intended as a + temporary measure, as it could be considered a security risk. ```shell git config --global http.sslVerify false @@ -204,10 +231,10 @@ A misconfiguration may result in: message: SSL_connect returned=1 errno=0 state=error: wrong version number (OpenSSL::SSL::SSLError) ``` -Some of these errors come from the Excon Ruby gem, and could be generated in circumstances -where GitLab is configured to initiate an HTTPS session to a remote server -that is serving just HTTP. +Some of these errors come from the Excon Ruby gem, and could be generated in +circumstances where GitLab is configured to initiate an HTTPS session to a +remote server that is serving only HTTP. -One scenario is that you're using [object storage](../object_storage.md) -which is not served under HTTPS. GitLab is misconfigured and attempts a TLS handshake, +One scenario is that you're using [object storage](../object_storage.md), which +isn't served under HTTPS. GitLab is misconfigured and attempts a TLS handshake, but the object storage will respond with plain HTTP. |