From 01715d85daa5fbf1f46337c75fe5d55dbfcd8804 Mon Sep 17 00:00:00 2001 From: Kamil Trzcinski <ayufan@ayufan.eu> Date: Fri, 20 Nov 2015 23:15:11 +0100 Subject: [PATCH] Add docs about the TLS usage --- README.md | 1 + docs/configuration/advanced-configuration.md | 2 + docs/configuration/tls-self-signed.md | 46 ++++++++++++++++++++ docs/faq/README.md | 6 ++- 4 files changed, 54 insertions(+), 1 deletion(-) create mode 100644 docs/configuration/tls-self-signed.md diff --git a/README.md b/README.md index dd4e4bb8b..880d61964 100644 --- a/README.md +++ b/README.md @@ -72,6 +72,7 @@ The config file is automatically migrated when GitLab Runner was installed from ### Advanced Configuration +* [See the self-signed certificates](docs/configuration/tls-self-signed.md) * [See advanced configuration options](docs/configuration/advanced-configuration.md) * [See example configuration file](config.toml.example) * [See security considerations](docs/security/index.md) diff --git a/docs/configuration/advanced-configuration.md b/docs/configuration/advanced-configuration.md index 80a0d7264..b55d12da6 100644 --- a/docs/configuration/advanced-configuration.md +++ b/docs/configuration/advanced-configuration.md @@ -28,6 +28,8 @@ This defines one runner entry. | `name` | not used, just informatory | | `url` | CI URL | | `token` | runner token | +| `tls-ca-file` | file containing the certificates to verify the peer when using HTTPS | +| `tls-skip-verify` | whether to verify the TLS certificate when using HTTPS, default: false | | `limit` | limit how many jobs can be handled concurrently by this token. 0 simply means don't limit | | `executor` | select how a project should be built, see next section | | `shell` | the name of shell to generate the script (default value is platform dependent) | diff --git a/docs/configuration/tls-self-signed.md b/docs/configuration/tls-self-signed.md new file mode 100644 index 000000000..8a3559743 --- /dev/null +++ b/docs/configuration/tls-self-signed.md @@ -0,0 +1,46 @@ +## The self-signed certificates or custom Certification Authorities + +Since version 0.7.0 the GitLab Runner have allows to configure certificates that are used to verify TLS peer when connecting GitLab server. + +**This allows to solve the `x509: certificate signed by unknown authority` problem when registering runner.** + +The GitLab Runner provides these options: + +1. **Default**: GitLab Runner reads system certificate store and verifies the GitLab server against the CA's stored in system. + +2. GitLab Runner reads the PEM (**DER format is not supported**) certificate from predefined file: + + - `/etc/gitlab-runner/certs/hostname.crt` on *nix systems when gitlab-runner is executed as root. + - `~/.gitlab-runner/certs/hostname.crt` on *nix systems when gitlab-runner is executed as non-root, + - `./certs/hostname.crt` on other systems. + + If address of your server is: `https://my.gitlab.server.com:8443/`. + Create the certificate file at: `/etc/gitlab-runner/certs/my.gitlab.server.com`. + +3. GitLab Runner exposes `tls-ca-file` option during registration and in [`config.toml`](advanced-configuration.md) +which allows you to specify custom file with certificates. This file will be read everytime when runner tries to +access the GitLab server. + +4. GitLab Runner exposes `tls-skip-verify` option during registration and [`config.toml`](advanced-configuration.md) +which allows you to skip TLS verification when connecting to server. +**This approach is INSECURE! Use at your own risk!** +Anyone can eavesdrop your connection: +- see the runner token which is used to authenticate against GitLab, +- see tokens which are used to clone GitLab projects, +- see the secure variables that are passed to runner. + +### Git cloning + +Currently the certificates are only used to verify connections between GitLab Runner and GitLab server. +This doesn't affect git commands (ie. `git clone`). +You still will see build errors due to TLS validation failure. + +To have maximum security for your builds you should configure `GIT_SSL_CAINFO` variable. +It allows you to define the file containing the certificates to verify the peer with when fetching or pushing over HTTPS + +The other options is to disable TLS verification, but as said before this approach is insecure. +Add to your `.gitlab-ci.yml` this lines: +``` +variables: + GIT_SSL_NO_VERIFY: "1" +``` diff --git a/docs/faq/README.md b/docs/faq/README.md index ee8d6a963..56ceb6963 100644 --- a/docs/faq/README.md +++ b/docs/faq/README.md @@ -29,4 +29,8 @@ project to use *git fetch* from the GitLab CI project settings page. The [NTFSSecurity](https://ntfssecurity.codeplex.com/) PowerShell module provides a *Remove-Item2* method which supports long paths. The Gitlab CI Multi Runner will -detect it if it is available and automatically make use of it. \ No newline at end of file +detect it if it is available and automatically make use of it. + +## 4. I'm seeing `x509: certificate signed by unknown authority` + +Please [See the self-signed certificates](../configuration/tls-self-signed.md) -- GitLab