Skip to content

G
gitlab-ce
Commit 0001cc89 authored by Craig Norris's avatar Craig Norris
Browse files
Options

Add Distribution metadata 

Add Distribution metadata and style updates.
parent af382cf2
Hide whitespace changes
Inline Side-by-side
Showing with 66 additions and 39 deletions
doc/administration/troubleshooting/ssl.md
View file @ 0001cc89
---
stage: none
group: unassigned
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:
......@@ -26,7 +29,8 @@ After configuring a GitLab instance with an internal CA certificate, you might n
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,11 +110,15 @@ 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:
......@@ -116,7 +130,7 @@ The cause of the issue can be confirmed by checking if:
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.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7