diff options
author | GitLab Bot <gitlab-bot@gitlab.com> | 2022-10-28 09:11:07 +0300 |
---|---|---|
committer | GitLab Bot <gitlab-bot@gitlab.com> | 2022-10-28 09:11:07 +0300 |
commit | 5431dbfffcd7ae1cacc9b68b719b0e8fea29e6a4 (patch) | |
tree | cea1c8e135c30db657bdd966e33d10ff0491244b /doc/administration/troubleshooting | |
parent | 6e2c5f5017e82e6f86488e89c2b709789c55bf90 (diff) |
Add latest changes from gitlab-org/gitlab@master
Diffstat (limited to 'doc/administration/troubleshooting')
-rw-r--r-- | doc/administration/troubleshooting/ssl.md | 266 |
1 files changed, 7 insertions, 259 deletions
diff --git a/doc/administration/troubleshooting/ssl.md b/doc/administration/troubleshooting/ssl.md index 245ff9f4982..bf8e6b45fde 100644 --- a/doc/administration/troubleshooting/ssl.md +++ b/doc/administration/troubleshooting/ssl.md @@ -1,263 +1,11 @@ --- -stage: Systems -group: Distribution -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 -type: reference +redirect_to: 'https://docs.gitlab.com/omnibus/settings/ssl/ssl_troubleshooting.html' +remove_date: '2023-10-27' --- -# Troubleshooting SSL **(FREE SELF)** +This document was moved to [another location](https://docs.gitlab.com/omnibus/settings/ssl/ssl_troubleshooting.html). -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 documentation: - -- [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). -- [Configure HTTPS manually](https://docs.gitlab.com/omnibus/settings/ssl.html#configure-https-manually). - -## 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 by using various CLI tools. You may experience the -following issues: - -- `curl` fails: - - ```shell - 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 by using the [rails console](../operations/rails_console.md#starting-a-rails-console-session) - also fails: - - ```ruby - uri = URI.parse("https://gitlab.domain.tld") - http = Net::HTTP.new(uri.host, uri.port) - http.use_ssl = true - http.verify_mode = 1 - response = http.request(Net::HTTP::Get.new(uri.request_uri)) - ... - Traceback (most recent call last): - 1: from (irb):5 - 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 displayed when setting up a [mirror](../../user/project/repository/mirror/index.md) - 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 -servername gitlab.domain.tld - ``` - -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 display -the following error message: - -`SSL: error:0B080074:x509 certificate routines:X509_check_private_key:key values mismatch` - -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: - -```shell -$ openssl rsa -noout -modulus -in private.key | openssl md5 -4f49b61b25225abeb7542b29ae20e98c -$ 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: - -```shell -$ openssl rsa -noout -modulus -in private.key | openssl md5 -d418865077299af27707b1d1fa83cd99 -$ openssl x509 -noout -modulus -in public.crt | openssl md5 -4f49b61b25225abeb7542b29ae20e98c -``` - -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 following error message: - -```shell -Dec 6 02:43:17 runner-host01 gitlab-runner[15131]: #033[0;33mWARNING: Checking for jobs... failed -#033[0;m #033[0;33mrunner#033[0;m=Bfkz1fyb #033[0;33mstatus#033[0;m=couldn't execute POST against -https://gitlab.domain.tld/api/v4/jobs/request: Post https://gitlab.domain.tld/api/v4/jobs/request: -x509: certificate signed by unknown authority -``` - -Follow the details in [Self-signed certificates or custom Certification Authorities for GitLab Runner](https://docs.gitlab.com/runner/configuration/tls-self-signed.html). - -## Mirroring a remote GitLab repository that uses a self-signed SSL certificate - -When configuring a local GitLab instance to [mirror a repository](../../user/project/repository/mirror/index.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: (60) SSL certificate problem: self signed certificate - More details here: https://curl.haxx.se/docs/sslcerts.html - ``` - -- Testing by using the Rails console also fails: - - ```ruby - uri = URI.parse("https://gitlab.domain.tld") - http = Net::HTTP.new(uri.host, uri.port) - http.use_ssl = true - http.verify_mode = 1 - response = http.request(Net::HTTP::Get.new(uri.request_uri)) - ... - Traceback (most recent call last): - 1: from (irb):5 - OpenSSL::SSL::SSLError (SSL_connect returned=1 errno=0 state=error: certificate verify failed (unable to get local issuer certificate)) - ``` - -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 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 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 &#39;https://gitlab.domain.tld/root/test-repo/&#39;: -SSL: unable to obtain common name from peer certificate -``` - -In this case, the problem can be related to the certificate itself: - -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 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 -Cloning into 'project'... -fatal: unable to access 'https://gitlab.domain.tld/group/project.git/': SSL certificate problem: self signed certificate -``` - -```shell -$ git clone https://gitlab.domain.tld/group/project.git -Cloning into 'project'... -fatal: unable to access 'https://gitlab.domain.tld/group/project.git/': server certificate verification failed. CAfile: /etc/ssl/certs/ca-certificates.crt CRLfile: none -``` - -To fix this problem: - -- 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: - - ```shell - git config --global http.sslCAInfo ~/.ssl/gitlab.domain.tld.crt - ``` - - - Disable SSL verification in your Git client. This is intended as a - temporary measure, as it could be considered a security risk. - - ```shell - git config --global http.sslVerify false - ``` - -## SSL_connect wrong version number - -A misconfiguration may result in: - -- `gitlab-rails/exceptions_json.log` entries containing: - - ```plaintext - "exception.class":"Excon::Error::Socket","exception.message":"SSL_connect returned=1 errno=0 state=error: wrong version number (OpenSSL::SSL::SSLError)", - "exception.class":"Excon::Error::Socket","exception.message":"SSL_connect returned=1 errno=0 state=error: wrong version number (OpenSSL::SSL::SSLError)", - ``` - -- `gitlab-workhorse/current` containing: - - ```plaintext - http: server gave HTTP response to HTTPS client - http: server gave HTTP response to HTTPS client - ``` - -- `gitlab-rails/sidekiq.log` or `sidekiq/current` containing: - - ```plaintext - message: SSL_connect returned=1 errno=0 state=error: wrong version number (OpenSSL::SSL::SSLError) - 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 only HTTP. - -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 responds with plain HTTP. - -## `schannel: SEC_E_UNTRUSTED_ROOT` - -If you're on Windows and get the following error: - -```plaintext -Fatal: unable to access 'https://gitlab.domain.tld/group/project.git': schannel: SEC_E_UNTRUSTED_ROOT (0x80090325) - The certificate chain was issued by an authority that is not trusted." -``` - -You must specify that Git should use OpenSSL: - -```shell -git config --system http.sslbackend openssl -``` - -Alternatively, you can ignore SSL verification by running: - -WARNING: -Proceed with caution when [ignoring SSL](https://git-scm.com/docs/git-config#Documentation/git-config.txt-httpsslVerify) -due to the potential security issues associated with disabling this option at global level. Use this option _only_ when troubleshooting, and reinstate SSL verification immediately after. - -```shell -git config --global http.sslVerify false -``` +<!-- This redirect file can be deleted after <2023-01-25>. --> +<!-- Redirects that point to other docs in the same project expire in three months. --> +<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> |