diff options
Diffstat (limited to 'doc/administration')
39 files changed, 467 insertions, 123 deletions
diff --git a/doc/administration/auth/README.md b/doc/administration/auth/README.md index d8094587d14..2fc9db0632e 100644 --- a/doc/administration/auth/README.md +++ b/doc/administration/auth/README.md @@ -1,19 +1,34 @@ --- comments: false +type: index --- -# Authentication and Authorization +# GitLab authentication and authorization GitLab integrates with the following external authentication and authorization -providers. +providers: -- [LDAP](ldap.md) Includes Active Directory, Apple Open Directory, Open LDAP, - and 389 Server +- [Auth0](../../integration/auth0.md) +- [Authentiq](authentiq.md) +- [Azure](../../integration/azure.md) +- [Bitbucket Cloud](../../integration/bitbucket.md) +- [CAS](../../integration/cas.md) +- [Crowd](../../integration/crowd.md) +- [Facebook](../../integration/facebook.md) +- [GitHub](../../integration/github.md) +- [GitLab.com](../../integration/gitlab.md) +- [Google](../../integration/google.md) +- [JWT](jwt.md) +- [Kerberos](../../integration/kerberos.md) +- [LDAP](ldap.md): Includes Active Directory, Apple Open Directory, Open LDAP, + and 389 Server. - [LDAP for GitLab EE](ldap-ee.md): LDAP additions to GitLab Enterprise Editions **(STARTER ONLY)** -- [OmniAuth](../../integration/omniauth.md) Sign in via Twitter, GitHub, GitLab.com, Google, - Bitbucket, Facebook, Shibboleth, Crowd, Azure, Authentiq ID, and JWT -- [CAS](../../integration/cas.md) Configure GitLab to sign in using CAS -- [SAML](../../integration/saml.md) Configure GitLab as a SAML 2.0 Service Provider -- [Okta](okta.md) Configure GitLab to sign in using Okta -- [Authentiq](authentiq.md): Enable the Authentiq OmniAuth provider for passwordless authentication -- [Smartcard](smartcard.md) Smartcard authentication **(PREMIUM ONLY)** + - [Google Secure LDAP](google_secure_ldap.md) +- [Okta](okta.md) +- [Salesforce](../../integration/salesforce.md) +- [SAML](../../integration/saml.md) +- [SAML for GitLab.com groups](../../user/group/saml_sso/index.md) **(SILVER ONLY)** +- [Shibboleth](../../integration/shibboleth.md) +- [Smartcard](smartcard.md) **(PREMIUM ONLY)** +- [Twitter](../../integration/twitter.md) +- [UltraAuth](../../integration/ultra_auth.md) diff --git a/doc/administration/auth/authentiq.md b/doc/administration/auth/authentiq.md index 835c97c0288..b84eca4ef0d 100644 --- a/doc/administration/auth/authentiq.md +++ b/doc/administration/auth/authentiq.md @@ -1,3 +1,7 @@ +--- +type: reference +--- + # Authentiq OmniAuth Provider To enable the Authentiq OmniAuth provider for passwordless authentication you must register an application with Authentiq. @@ -66,3 +70,15 @@ On the sign in page there should now be an Authentiq icon below the regular sign - If not they will be prompted to download the app and then follow the procedure above. If everything goes right, the user will be returned to GitLab and will be signed in. + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/administration/auth/crowd.md b/doc/administration/auth/crowd.md index 86c7bad2ebf..ac63b4f2b97 100644 --- a/doc/administration/auth/crowd.md +++ b/doc/administration/auth/crowd.md @@ -1,5 +1,11 @@ +--- +type: reference +--- + # Atlassian Crowd OmniAuth Provider +Authenticate to GitLab using the Atlassian Crowd OmniAuth provider. + ## Configure a new Crowd application 1. Choose 'Applications' in the top menu, then 'Add application'. diff --git a/doc/administration/auth/google_secure_ldap.md b/doc/administration/auth/google_secure_ldap.md index 0e6d7ff1df1..55e6f53622c 100644 --- a/doc/administration/auth/google_secure_ldap.md +++ b/doc/administration/auth/google_secure_ldap.md @@ -1,3 +1,7 @@ +--- +type: reference +--- + # Google Secure LDAP **(CORE ONLY)** > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/46391) in GitLab 11.9. @@ -204,3 +208,15 @@ values obtained during the LDAP client configuration earlier: [reconfigure]: ../restart_gitlab.md#omnibus-gitlab-reconfigure [restart]: ../restart_gitlab.md#installations-from-source + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/administration/auth/how_to_configure_ldap_gitlab_ce/index.md b/doc/administration/auth/how_to_configure_ldap_gitlab_ce/index.md index 320a65b665d..86dd398343b 100644 --- a/doc/administration/auth/how_to_configure_ldap_gitlab_ce/index.md +++ b/doc/administration/auth/how_to_configure_ldap_gitlab_ce/index.md @@ -1,15 +1,9 @@ --- -author: Chris Wilson -author_gitlab: MrChrisW -level: intermediary -article_type: admin guide -date: 2017-05-03 +type: howto --- # How to configure LDAP with GitLab CE -## Introduction - Managing a large number of users in GitLab can become a burden for system administrators. As an organization grows so do user accounts. Keeping these user accounts in sync across multiple enterprise applications often becomes a time consuming task. In this guide we will focus on configuring GitLab with Active Directory. [Active Directory](https://en.wikipedia.org/wiki/Active_Directory) is a popular LDAP compatible directory service provided by Microsoft, included in all modern Windows Server operating systems. @@ -268,3 +262,15 @@ have extended functionalities with LDAP, such as: - Multiple LDAP servers Read through the article on [LDAP for GitLab EE](../how_to_configure_ldap_gitlab_ee/index.md) **(STARTER ONLY)** for an overview. + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/administration/auth/how_to_configure_ldap_gitlab_ee/index.md b/doc/administration/auth/how_to_configure_ldap_gitlab_ee/index.md index 2683950f143..366acb9ed3e 100644 --- a/doc/administration/auth/how_to_configure_ldap_gitlab_ee/index.md +++ b/doc/administration/auth/how_to_configure_ldap_gitlab_ee/index.md @@ -1,16 +1,10 @@ --- -author: Chris Wilson -author_gitlab: MrChrisW -level: intermediary -article_type: admin guide -date: 2017-05-03 +type: howto --- # How to configure LDAP with GitLab EE **(STARTER ONLY)** -## Introduction - -The present article follows [How to Configure LDAP with GitLab CE](../how_to_configure_ldap_gitlab_ce/index.md). Make sure to read through it before moving forward. +This article expands on [How to Configure LDAP with GitLab CE](../how_to_configure_ldap_gitlab_ce/index.md). Make sure to read through it before moving forward. ## GitLab Enterprise Edition - LDAP features @@ -117,3 +111,15 @@ Integration of GitLab with Active Directory (LDAP) reduces the complexity of use It has the advantage of improving user permission controls, whilst easing the deployment of GitLab into an existing [IT environment](https://www.techopedia.com/definition/29199/it-infrastructure). GitLab EE offers advanced group management and multiple LDAP servers. With the assistance of the [GitLab Support](https://about.gitlab.com/support) team, setting up GitLab with an existing AD/LDAP solution will be a smooth and painless process. + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/administration/auth/jwt.md b/doc/administration/auth/jwt.md index 7db22bdd5df..e6b3287ce60 100644 --- a/doc/administration/auth/jwt.md +++ b/doc/administration/auth/jwt.md @@ -1,3 +1,7 @@ +--- +type: reference +--- + # JWT OmniAuth provider To enable the JWT OmniAuth provider, you must register your application with JWT. @@ -70,3 +74,15 @@ will be redirected to GitLab and will be signed in. [reconfigure]: ../restart_gitlab.md#omnibus-gitlab-reconfigure [restart GitLab]: ../restart_gitlab.md#installations-from-source + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/administration/auth/ldap-ee.md b/doc/administration/auth/ldap-ee.md index 2afac23c20c..2f2ee8a27d3 100644 --- a/doc/administration/auth/ldap-ee.md +++ b/doc/administration/auth/ldap-ee.md @@ -1,3 +1,7 @@ +--- +type: reference +--- + # LDAP Additions in GitLab EE **(STARTER ONLY)** This is a continuation of the main [LDAP documentation](ldap.md), detailing LDAP diff --git a/doc/administration/auth/ldap.md b/doc/administration/auth/ldap.md index 86e6be5f4fa..be05a4d63a7 100644 --- a/doc/administration/auth/ldap.md +++ b/doc/administration/auth/ldap.md @@ -1,3 +1,7 @@ +--- +type: reference +--- + <!-- If the change is EE-specific, put it in `ldap-ee.md`, NOT here. --> # LDAP @@ -494,6 +498,13 @@ be mandatory and clients cannot be authenticated with the TLS protocol. ## Troubleshooting +If a user account is blocked or unblocked due to the LDAP configuration, a +message will be logged to `application.log`. + +If there is an unexpected error during an LDAP lookup (configuration error, +timeout), the login is rejected and a message will be logged to +`production.log`. + ### Debug LDAP user filter with ldapsearch This example uses ldapsearch and assumes you are using ActiveDirectory. The @@ -527,18 +538,9 @@ ldapsearch -H ldaps://$host:$port -D "$bind_dn" -y bind_dn_password.txt -b "$ba sudo -u git -H bundle exec rake gitlab:ldap:check RAILS_ENV=production ``` -### Connection Refused +### Connection refused If you are getting 'Connection Refused' errors when trying to connect to the LDAP server please double-check the LDAP `port` and `encryption` settings used by GitLab. Common combinations are `encryption: 'plain'` and `port: 389`, OR `encryption: 'simple_tls'` and `port: 636`. - -### Troubleshooting - -If a user account is blocked or unblocked due to the LDAP configuration, a -message will be logged to `application.log`. - -If there is an unexpected error during an LDAP lookup (configuration error, -timeout), the login is rejected and a message will be logged to -`production.log`. diff --git a/doc/administration/auth/oidc.md b/doc/administration/auth/oidc.md index 454da8c2866..78d040cda99 100644 --- a/doc/administration/auth/oidc.md +++ b/doc/administration/auth/oidc.md @@ -1,3 +1,7 @@ +--- +type: reference +--- + # OpenID Connect OmniAuth provider GitLab can use [OpenID Connect](https://openid.net/specs/openid-connect-core-1_0.html) as an OmniAuth provider. @@ -81,6 +85,13 @@ The OpenID Connect will provide you with a client details and secret for you to - `<your_oidc_url>` (optional) is the URL that points to the OpenID Connect provider. For example, `https://example.com/auth/realms/your-realm`. If this value is not provided, the URL is constructed from the `client_options` in the following format: `<client_options.scheme>://<client_options.host>:<client_options.port>`. - If `discovery` is set to `true`, the OpenID Connect provider will try to auto discover the client options using `<your_oidc_url>/.well-known/openid-configuration`. Defaults to `false`. + - `client_auth_method` (optional) specifies the method used for authenticating the client with the OpenID Connect provider. + - Supported values are: + - `basic` - HTTP Basic Authentication + - `jwt_bearer` - JWT based authentication (private key and client secret signing) + - `mtls` - Mutual TLS or X.509 certificate validation + - Any other value will POST the client id and secret in the request body + - If not specified, defaults to `basic`. - `<uid_field>` (optional) is the field name from the `user_info` details that will be used as `uid` value. For example, `preferred_username`. If this value is not provided or the field with the configured value is missing from the `user_info` details, the `uid` will use the `sub` field. - `client_options` are the OpenID Connect client-specific options. Specifically: @@ -139,7 +150,7 @@ for more details: } ``` -### Troubleshooting +## Troubleshooting If you're having trouble, here are some tips: @@ -155,9 +166,9 @@ If you're having trouble, here are some tips: `https://accounts.google.com/.well-known/openid-configuration`. 1. The OpenID Connect client uses HTTP Basic Authentication to send the - OAuth2 access token. For example, if you are seeing 401 errors upon - retrieving the `userinfo` endpoint, you may want to check your OpenID - Web server configuration. For example, for + OAuth2 access token if `client_auth_method` is not defined or if set to `basic`. + If you are seeing 401 errors upon retrieving the `userinfo` endpoint, you may + want to check your OpenID Web server configuration. For example, for [oauth2-server-php](https://github.com/bshaffer/oauth2-server-php), you may need to [add a configuration parameter to Apache](https://github.com/bshaffer/oauth2-server-php/issues/926#issuecomment-387502778). diff --git a/doc/administration/auth/okta.md b/doc/administration/auth/okta.md index 566003ba708..5524c3ba092 100644 --- a/doc/administration/auth/okta.md +++ b/doc/administration/auth/okta.md @@ -1,3 +1,7 @@ +--- +type: reference +--- + # Okta SSO provider Okta is a [Single Sign-on provider](https://www.okta.com/products/single-sign-on/) that can be used to authenticate @@ -157,3 +161,15 @@ Make sure the groups exist and are assigned to the Okta app. You can take a look of the [SAML documentation](../../integration/saml.md#marking-users-as-external-based-on-saml-groups) on external groups since it works the same. + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/administration/auth/smartcard.md b/doc/administration/auth/smartcard.md index e47751e0cc5..4f236d1afb8 100644 --- a/doc/administration/auth/smartcard.md +++ b/doc/administration/auth/smartcard.md @@ -1,3 +1,7 @@ +--- +type: reference +--- + # Smartcard authentication **(PREMIUM ONLY)** GitLab supports authentication using smartcards. @@ -22,7 +26,7 @@ To use a smartcard with an X.509 certificate to authenticate against a local database with GitLab, `CN` and `emailAddress` must be defined in the certificate. For example: -``` +```text Certificate: Data: Version: 1 (0x0) @@ -212,3 +216,15 @@ attribute. As a prerequisite, you must use an LDAP server that: 1. Save the file and [restart](../restart_gitlab.md#installations-from-source) GitLab for the changes to take effect. + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/administration/geo/disaster_recovery/background_verification.md b/doc/administration/geo/disaster_recovery/background_verification.md index 8eee9427b56..27866b7536e 100644 --- a/doc/administration/geo/disaster_recovery/background_verification.md +++ b/doc/administration/geo/disaster_recovery/background_verification.md @@ -171,14 +171,21 @@ If the **primary** and **secondary** nodes have a checksum verification mismatch ## Current limitations -Until [issue #5064][ee-5064] is completed, background verification doesn't cover -CI job artifacts and traces, LFS objects, or user uploads in file storage. -Verify their integrity manually by following [these instructions][foreground-verification] -on both nodes, and comparing the output between them. +Automatic background verification doesn't cover attachments, LFS objects, +job artifacts, and user uploads in file storage. You can keep track of the +progress to include them in [ee-1430]. For now, you can verify their integrity +manually by following [these instructions][foreground-verification] on both +nodes, and comparing the output between them. + +In GitLab EE 12.1, Geo calculates checksums for attachments, LFS objects and +archived traces on secondary nodes after the transfer, compares it with the +stored checksums, and rejects transfers if mismatched. Please note that Geo +currently does not support an automatic way to verify these data if they have +been synced before GitLab EE 12.1. Data in object storage is **not verified**, as the object store is responsible for ensuring the integrity of the data. [reset-verification]: background_verification.md#reset-verification-for-projects-where-verification-has-failed [foreground-verification]: ../../raketasks/check.md -[ee-5064]: https://gitlab.com/gitlab-org/gitlab-ee/issues/5064 +[ee-1430]: https://gitlab.com/groups/gitlab-org/-/epics/1430 diff --git a/doc/administration/geo/replication/external_database.md b/doc/administration/geo/replication/external_database.md index 85687d4a648..256195998a7 100644 --- a/doc/administration/geo/replication/external_database.md +++ b/doc/administration/geo/replication/external_database.md @@ -25,7 +25,6 @@ developed and tested. We aim to be compatible with most external This command will use your defined `external_url` in `/etc/gitlab/gitlab.rb`. - ### Configure the external database to be replicated To set up an external database, you can either: diff --git a/doc/administration/geo/replication/updating_the_geo_nodes.md b/doc/administration/geo/replication/updating_the_geo_nodes.md index c27f6c78455..166ee94eca4 100644 --- a/doc/administration/geo/replication/updating_the_geo_nodes.md +++ b/doc/administration/geo/replication/updating_the_geo_nodes.md @@ -14,6 +14,16 @@ all you need to do is update GitLab itself: the tracking database is enabled. 1. [Test](#check-status-after-updating) **primary** and **secondary** nodes, and check version in each. +## Upgrading to GitLab 12.1 + +By default, GitLab 12.1 will attempt to automatically upgrade the embedded PostgreSQL server to 10.7 from 9.6. Please see [the omnibus documentation](https://docs.gitlab.com/omnibus/settings/database.html#upgrading-a-geo-instance) for the recommended procedure. + +This can be temporarily disabled by running the following before ugprading: + +```sh +sudo touch /etc/gitlab/disable-postgresql-upgrade +``` + ## Upgrading to GitLab 10.8 Before 10.8, broadcast messages would not propagate without flushing the cache on the **secondary** nodes. This has been fixed in 10.8, but requires one last cache flush on each **secondary** node: diff --git a/doc/administration/high_availability/README.md b/doc/administration/high_availability/README.md index 4317d14ba68..41ef68f5b57 100644 --- a/doc/administration/high_availability/README.md +++ b/doc/administration/high_availability/README.md @@ -1,3 +1,7 @@ +--- +type: reference, concepts +--- + # Scaling and High Availability GitLab supports several different types of clustering and high-availability. diff --git a/doc/administration/high_availability/alpha_database.md b/doc/administration/high_availability/alpha_database.md index 7bf20be60e6..7afd739f44c 100644 --- a/doc/administration/high_availability/alpha_database.md +++ b/doc/administration/high_availability/alpha_database.md @@ -2,5 +2,4 @@ redirect_to: 'database.md' --- -This documentation has been moved to the main -[database documentation](database.md#configure_using_omnibus_for_high_availability). +This document was moved to [another location](database.md). diff --git a/doc/administration/high_availability/consul.md b/doc/administration/high_availability/consul.md index 1f93c8130d3..b02a61b9256 100644 --- a/doc/administration/high_availability/consul.md +++ b/doc/administration/high_availability/consul.md @@ -1,6 +1,8 @@ -# Working with the bundled Consul service **(PREMIUM ONLY)** +--- +type: reference +--- -## Overview +# Working with the bundled Consul service **(PREMIUM ONLY)** As part of its High Availability stack, GitLab Premium includes a bundled version of [Consul](https://www.consul.io/) that can be managed through `/etc/gitlab/gitlab.rb`. diff --git a/doc/administration/high_availability/database.md b/doc/administration/high_availability/database.md index 1702a731647..f7a1f425b40 100644 --- a/doc/administration/high_availability/database.md +++ b/doc/administration/high_availability/database.md @@ -1,5 +1,12 @@ +--- +type: reference +--- + # Configuring PostgreSQL for Scaling and High Availability +In this section, you'll be guided through configuring a PostgreSQL database +to be used with GitLab in a highly available environment. + ## Provide your own PostgreSQL instance **(CORE ONLY)** If you're hosting GitLab on a cloud provider, you can optionally use a diff --git a/doc/administration/high_availability/gitaly.md b/doc/administration/high_availability/gitaly.md index b7eaa4ce105..739d1ae35fb 100644 --- a/doc/administration/high_availability/gitaly.md +++ b/doc/administration/high_availability/gitaly.md @@ -1,3 +1,7 @@ +--- +type: reference +--- + # Configuring Gitaly for Scaled and High Availability Gitaly does not yet support full high availability. However, Gitaly is quite @@ -46,3 +50,15 @@ Continue configuration of other components by going back to: ``` 1. Run `sudo gitlab-ctl reconfigure` to compile the configuration. + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/administration/high_availability/gitlab.md b/doc/administration/high_availability/gitlab.md index 83838928519..8818a9606de 100644 --- a/doc/administration/high_availability/gitlab.md +++ b/doc/administration/high_availability/gitlab.md @@ -1,4 +1,8 @@ -# Configuring GitLab Scaling and High Availability +--- +type: reference +--- + +# Configuring GitLab for Scaling and High Availability > **Note:** There is some additional configuration near the bottom for additional GitLab application servers. It's important to read and understand diff --git a/doc/administration/high_availability/load_balancer.md b/doc/administration/high_availability/load_balancer.md index 28b226cacd5..9e9f604317a 100644 --- a/doc/administration/high_availability/load_balancer.md +++ b/doc/administration/high_availability/load_balancer.md @@ -1,3 +1,7 @@ +--- +type: reference +--- + # Load Balancer for GitLab HA In an active/active GitLab configuration, you will need a load balancer to route @@ -114,3 +118,15 @@ Read more on high-availability configuration: if SSL was terminated at the load balancer. [gitlab-pages]: ../pages/index.md + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/administration/high_availability/monitoring_node.md b/doc/administration/high_availability/monitoring_node.md index cbc1d4bcd52..b91a994d01e 100644 --- a/doc/administration/high_availability/monitoring_node.md +++ b/doc/administration/high_availability/monitoring_node.md @@ -1,7 +1,13 @@ +--- +type: reference +--- + # Configuring a Monitoring node for Scaling and High Availability > [Introduced](https://gitlab.com/gitlab-org/omnibus-gitlab/issues/3786) in GitLab 12.0. +You can configure a Prometheus node to monitor GitLab. + ## Standalone Monitoring node using GitLab Omnibus The GitLab Omnibus package can be used to configure a standalone Monitoring node running [Prometheus](../monitoring/prometheus/index.md) and [Grafana](../monitoring/performance/grafana_configuration.md). @@ -67,3 +73,15 @@ Once monitoring using Service Discovery is enabled with `consul['monitoring_serv ensure that `prometheus['scrape_configs']` is not set in `/etc/gitlab/gitlab.rb`. Setting both `consul['monitoring_service_discovery'] = true` and `prometheus['scrape_configs']` in `/etc/gitlab/gitlab.rb` will result in errors. + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/administration/high_availability/nfs.md b/doc/administration/high_availability/nfs.md index 6ab6b8bed30..294f0e969d5 100644 --- a/doc/administration/high_availability/nfs.md +++ b/doc/administration/high_availability/nfs.md @@ -1,3 +1,7 @@ +--- +type: reference +--- + # NFS You can view information and options set for each of the mounted NFS file @@ -47,29 +51,15 @@ management between systems: ### Improving NFS performance with GitLab -NOTE: **Note:** This is only available starting in certain versions of GitLab: 11.5.11, -11.6.11, 11.7.12, 11.8.8, 11.9.0 and up (e.g. 11.10, 11.11, etc.) +NOTE: **Note:** From GitLab 12.1, it will automatically be detected if Rugged can and should be used per storage. -If you are using NFS to share Git data, we recommend that you enable a -number of feature flags that will allow GitLab application processes to -access Git data directly instead of going through the [Gitaly -service](../gitaly/index.md). Depending on your workload and disk -performance, these flags may help improve performance. See [the -issue](https://gitlab.com/gitlab-org/gitlab-ce/issues/57317) for more -details. - -To do this, run the Rake task: +If you previously enabled Rugged using the feature flag, you will need to unset the feature flag by using: ```sh -sudo gitlab-rake gitlab:features:enable_rugged +sudo gitlab-rake gitlab:features:unset_rugged ``` -If you need to undo this setting for some reason such as switching to [Gitaly without NFS](gitaly.md) -(recommended), run: - -```sh -sudo gitlab-rake gitlab:features:disable_rugged -``` +If the Rugged feature flag is explicitly set to either true or false, GitLab will use the value explicitly set. ### Known issues @@ -236,3 +226,15 @@ Read more on high-availability configuration: 1. [Configure the load balancers](load_balancer.md) [udp-log-shipping]: https://docs.gitlab.com/omnibus/settings/logs.html#udp-log-shipping-gitlab-enterprise-edition-only "UDP log shipping" + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/administration/high_availability/nfs_host_client_setup.md b/doc/administration/high_availability/nfs_host_client_setup.md index a8d69b9ab0a..9b0e085fe25 100644 --- a/doc/administration/high_availability/nfs_host_client_setup.md +++ b/doc/administration/high_availability/nfs_host_client_setup.md @@ -1,3 +1,7 @@ +--- +type: reference +--- + # Configuring NFS for GitLab HA Setting up NFS for a GitLab HA setup allows all applications nodes in a cluster @@ -133,3 +137,15 @@ client with the command below. ```sh sudo ufw allow from <client-ip-address> to any port nfs ``` + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/administration/high_availability/pgbouncer.md b/doc/administration/high_availability/pgbouncer.md index 6890b0f7db7..0b945bc6244 100644 --- a/doc/administration/high_availability/pgbouncer.md +++ b/doc/administration/high_availability/pgbouncer.md @@ -1,6 +1,8 @@ -# Working with the bundle Pgbouncer service +--- +type: reference +--- -## Overview +# Working with the bundle Pgbouncer service As part of its High Availability stack, GitLab Premium includes a bundled version of [Pgbouncer](https://pgbouncer.github.io/) that can be managed through `/etc/gitlab/gitlab.rb`. diff --git a/doc/administration/high_availability/redis.md b/doc/administration/high_availability/redis.md index c29514ed9f6..1b79dde9476 100644 --- a/doc/administration/high_availability/redis.md +++ b/doc/administration/high_availability/redis.md @@ -1,3 +1,7 @@ +--- +type: reference +--- + # Configuring Redis for Scaling and High Availability ## Provide your own Redis instance **(CORE ONLY)** diff --git a/doc/administration/high_availability/redis_source.md b/doc/administration/high_availability/redis_source.md index a5463e5128c..63915e5d96c 100644 --- a/doc/administration/high_availability/redis_source.md +++ b/doc/administration/high_availability/redis_source.md @@ -1,3 +1,7 @@ +--- +type: reference +--- + # Configuring non-Omnibus Redis for GitLab HA This is the documentation for configuring a Highly Available Redis setup when diff --git a/doc/administration/housekeeping.md b/doc/administration/housekeeping.md index 1b01419e062..abe39d188aa 100644 --- a/doc/administration/housekeeping.md +++ b/doc/administration/housekeeping.md @@ -2,7 +2,6 @@ > [Introduced][ce-2371] in GitLab 8.4. ---- ## Automatic housekeeping GitLab automatically runs `git gc` and `git repack` on repositories @@ -32,8 +31,6 @@ the `pushes_since_gc` value is 200 a `git gc` will be run. You can find this option under your project's **Settings > General > Advanced**. ---- -  [ce-2371]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/2371 "Housekeeping merge request" diff --git a/doc/administration/job_artifacts.md b/doc/administration/job_artifacts.md index 9df7b2526e2..5490a59ceac 100644 --- a/doc/administration/job_artifacts.md +++ b/doc/administration/job_artifacts.md @@ -13,8 +13,6 @@ if you want to know how to disable it. To disable artifacts site-wide, follow the steps below. ---- - **In Omnibus installations:** 1. Edit `/etc/gitlab/gitlab.rb` and add the following line: @@ -25,8 +23,6 @@ To disable artifacts site-wide, follow the steps below. 1. Save the file and [reconfigure GitLab][] for the changes to take effect. ---- - **In installations from source:** 1. Edit `/home/git/gitlab/config/gitlab.yml` and add or amend the following lines: @@ -49,8 +45,6 @@ this is done when the job succeeds, but can also be done on failure, or always, To change the location where the artifacts are stored locally, follow the steps below. ---- - **In Omnibus installations:** _The artifacts are stored by default in @@ -65,8 +59,6 @@ _The artifacts are stored by default in 1. Save the file and [reconfigure GitLab][] for the changes to take effect. ---- - **In installations from source:** _The artifacts are stored by default in @@ -167,8 +159,6 @@ _The artifacts are stored by default in gitlab-rake gitlab:artifacts:migrate ``` ---- - **In installations from source:** _The artifacts are stored by default in @@ -207,8 +197,6 @@ right after that date passes. Artifacts are cleaned up by the To change the default schedule on which the artifacts are expired, follow the steps below. ---- - **In Omnibus installations:** 1. Edit `/etc/gitlab/gitlab.rb` and comment out or add the following line @@ -219,8 +207,6 @@ steps below. 1. Save the file and [reconfigure GitLab][] for the changes to take effect. ---- - **In installations from source:** 1. Edit `/home/git/gitlab/config/gitlab.yml` and add or amend the following @@ -240,8 +226,6 @@ steps below. To disable [the dependencies validation](../ci/yaml/README.md#when-a-dependent-job-will-fail), you can flip the feature flag from a Rails console. ---- - **In Omnibus installations:** 1. Enter the Rails console: @@ -256,8 +240,6 @@ you can flip the feature flag from a Rails console. Feature.enable('ci_disable_validates_dependencies') ``` ---- - **In installations from source:** 1. Enter the Rails console: diff --git a/doc/administration/monitoring/performance/gitlab_configuration.md b/doc/administration/monitoring/performance/gitlab_configuration.md index 771584268d9..9a25cc04ee7 100644 --- a/doc/administration/monitoring/performance/gitlab_configuration.md +++ b/doc/administration/monitoring/performance/gitlab_configuration.md @@ -8,12 +8,8 @@ The minimum required settings you need to set are the InfluxDB host and port. Make sure _Enable InfluxDB Metrics_ is checked and hit **Save** to save the changes. ---- -  ---- - Finally, a restart of all GitLab processes is required for the changes to take effect: @@ -30,8 +26,6 @@ sudo service gitlab restart When any migrations are pending, the metrics are disabled until the migrations have been performed. ---- - Read more on: - [Introduction to GitLab Performance Monitoring](introduction.md) diff --git a/doc/administration/monitoring/performance/performance_bar.md b/doc/administration/monitoring/performance/performance_bar.md index 95f497a1470..4ee156fdc11 100644 --- a/doc/administration/monitoring/performance/performance_bar.md +++ b/doc/administration/monitoring/performance/performance_bar.md @@ -40,10 +40,6 @@ display it. You can toggle the Bar using the same shortcut. ---- -  ---- - [Gitaly]: ../../gitaly/index.md diff --git a/doc/administration/monitoring/prometheus/index.md b/doc/administration/monitoring/prometheus/index.md index 341ea3330d7..c8968c51393 100644 --- a/doc/administration/monitoring/prometheus/index.md +++ b/doc/administration/monitoring/prometheus/index.md @@ -134,17 +134,57 @@ To use an external Prometheus server: ```yaml scrape_configs: - - job_name: 'gitlab_exporters' + - job_name: nginx static_configs: - - targets: ['1.1.1.1:9168', '1.1.1.1:9236', '1.1.1.1:9236', '1.1.1.1:9100', '1.1.1.1:9121', '1.1.1.1:9187'] - - - job_name: 'gitlab_metrics' - metrics_path: /-/metrics + - targets: + - 1.1.1.1:8060 + - job_name: redis + static_configs: + - targets: + - 1.1.1.1:9121 + - job_name: postgres + static_configs: + - targets: + - 1.1.1.1:9187 + - job_name: node + static_configs: + - targets: + - 1.1.1.1:9100 + - job_name: gitlab-workhorse + static_configs: + - targets: + - 1.1.1.1:9229 + - job_name: gitlab-rails + metrics_path: "/-/metrics" + static_configs: + - targets: + - 1.1.1.1:8080 + - job_name: gitlab-sidekiq + static_configs: + - targets: + - 1.1.1.1:8082 + - job_name: gitlab_monitor_database + metrics_path: "/database" + static_configs: + - targets: + - 1.1.1.1:9168 + - job_name: gitlab_monitor_sidekiq + metrics_path: "/sidekiq" + static_configs: + - targets: + - 1.1.1.1:9168 + - job_name: gitlab_monitor_process + metrics_path: "/process" + static_configs: + - targets: + - 1.1.1.1:9168 + - job_name: gitaly static_configs: - - targets: ['1.1.1.1:443'] + - targets: + - 1.1.1.1:9236 ``` -1. Restart the Prometheus server. +1. Reload the Prometheus server. ## Viewing performance metrics diff --git a/doc/administration/pages/img/lets_encrypt_integration_v12_1.png b/doc/administration/pages/img/lets_encrypt_integration_v12_1.png Binary files differnew file mode 100644 index 00000000000..5ab63074e12 --- /dev/null +++ b/doc/administration/pages/img/lets_encrypt_integration_v12_1.png diff --git a/doc/administration/pages/index.md b/doc/administration/pages/index.md index b5b8f124274..774e7056845 100644 --- a/doc/administration/pages/index.md +++ b/doc/administration/pages/index.md @@ -256,7 +256,7 @@ world. Custom domains and TLS are supported. ### Custom domain verification To prevent malicious users from hijacking domains that don't belong to them, -GitLab supports [custom domain verification](../../user/project/pages/getting_started_part_three.md#dns-txt-record). +GitLab supports [custom domain verification](../../user/project/pages/custom_domains_ssl_tls_certification/index.md#steps). When adding a custom domain, users will be required to prove they own it by adding a GitLab-controlled verification code to the DNS records for that domain. @@ -265,6 +265,23 @@ verification requirement. Navigate to `Admin area ➔ Settings` and uncheck **Require users to prove ownership of custom domains** in the Pages section. This setting is enabled by default. +### Let's Encrypt integration + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/28996) in GitLab 12.1. + +[GitLab Pages' Let's Encrypt integration](../../user/project/pages/custom_domains_ssl_tls_certification/lets_encrypt_integration.md) +allows users to add Let's Encrypt SSL certificates for GitLab Pages +sites served under a custom domain. + +To enable it, you'll need to: + +1. Choose an email on which you will recieve notifications about expiring domains. +1. Navigate to your instance's **Admin Area > Settings > Preferences** and expand **Pages** settings. +1. Enter the email for receiving notifications and accept Let's Encrypt's Terms of Service as shown below. +1. Click **Save changes**. + + + ### Access control > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/33422) in GitLab 11.5. diff --git a/doc/administration/raketasks/maintenance.md b/doc/administration/raketasks/maintenance.md index 2b31233d429..8d0b5b42515 100644 --- a/doc/administration/raketasks/maintenance.md +++ b/doc/administration/raketasks/maintenance.md @@ -251,3 +251,22 @@ sudo gitlab-rake gitlab:exclusive_lease:clear[project_housekeeping:*] # to clear a lease for repository garbage collection in a specific project: (id=4) sudo gitlab-rake gitlab:exclusive_lease:clear[project_housekeeping:4] ``` + +## Display status of database migrations + +To check the status of migrations, you can use the following rake task: + +```bash +sudo gitlab-rake db:migrate:status +``` + +This will output a table with a `Status` of `up` or `down` for +each Migration ID. + +```bash +database: gitlabhq_production + + Status Migration ID Migration Name +-------------------------------------------------- + up migration_id migration_name +```
\ No newline at end of file diff --git a/doc/administration/repository_checks.md b/doc/administration/repository_checks.md index 7cf8f20a9dc..05a7cb006a3 100644 --- a/doc/administration/repository_checks.md +++ b/doc/administration/repository_checks.md @@ -33,8 +33,8 @@ in `repocheck.log`: - in the [admin panel](logs.md#repochecklog) - or on disk, see: - - `/var/log/gitlab/gitlab-rails` for Omnibus installations - - `/home/git/gitlab/log` for installations from source + - `/var/log/gitlab/gitlab-rails` for Omnibus installations + - `/home/git/gitlab/log` for installations from source If for some reason the periodic repository check caused a lot of false alarms you can choose to clear *all* repository check states by diff --git a/doc/administration/repository_storage_paths.md b/doc/administration/repository_storage_paths.md index 3de860f9240..ad3a9b19c3c 100644 --- a/doc/administration/repository_storage_paths.md +++ b/doc/administration/repository_storage_paths.md @@ -55,8 +55,6 @@ storage2: > don't specify the full repository path but the parent path), but not for source > installations. ---- - Now that you've read that big fat warning above, let's edit the configuration files and add the full paths of the alternative repository storage paths. In the example below, we add two more mountpoints that are named `nfs` and `cephfs` @@ -90,8 +88,6 @@ are upgrading from a version prior to 8.10, make sure to add the configuration as described in the step above. After you make the changes and confirm they are working, you can remove the `repos_path` line. ---- - **For Omnibus installations** 1. Edit `/etc/gitlab/gitlab.rb` by appending the rest of the paths to the diff --git a/doc/administration/uploads.md b/doc/administration/uploads.md index 277d42d06c6..51e267c865e 100644 --- a/doc/administration/uploads.md +++ b/doc/administration/uploads.md @@ -10,8 +10,6 @@ This is the default configuration To change the location where the uploads are stored locally, follow the steps below. ---- - **In Omnibus installations:** NOTE: **Note:** @@ -29,8 +27,6 @@ _The uploads are stored by default in `/var/opt/gitlab/gitlab-rails/uploads`._ 1. Save the file and [reconfigure GitLab][] for the changes to take effect. ---- - **In installations from source:** _The uploads are stored by default in @@ -121,8 +117,6 @@ _The uploads are stored by default in 1. Save the file and [reconfigure GitLab][] for the changes to take effect. 1. Migrate any existing local uploads to the object storage using [`gitlab:uploads:migrate` rake task](raketasks/uploads/migrate.md). ---- - **In installations from source:** _The uploads are stored by default in @@ -146,6 +140,75 @@ _The uploads are stored by default in 1. Save the file and [restart GitLab][] for the changes to take effect. 1. Migrate any existing local uploads to the object storage using [`gitlab:uploads:migrate` rake task](raketasks/uploads/migrate.md). +### OpenStack compatible connection settings + +The connection settings match those provided by [Fog](https://github.com/fog), and are as follows: + +| Setting | Description | Default | +|---------|-------------|---------| +| `provider` | Always `OpenStack` for compatible hosts | OpenStack | +| `openstack_username` | OpenStack username | | +| `openstack_api_key` | OpenStack api key | | +| `openstack_temp_url_key` | OpenStack key for generating temporary urls | | +| `openstack_auth_url` | OpenStack authentication endpont | | +| `openstack_region` | OpenStack region | | +| `openstack_tenant` | OpenStack tenant ID | + +**In Omnibus installations:** + +_The uploads are stored by default in +`/var/opt/gitlab/gitlab-rails/public/uploads/-/system`._ + +1. Edit `/etc/gitlab/gitlab.rb` and add the following lines by replacing with + the values you want: + + ```ruby + gitlab_rails['uploads_object_store_remote_directory'] = "OPENSTACK_OBJECT_CONTAINER_NAME" + gitlab_rails['uploads_object_store_connection'] = { + 'provider' => 'OpenStack', + 'openstack_username' => 'OPENSTACK_USERNAME', + 'openstack_api_key' => 'OPENSTACK_PASSWORD', + 'openstack_temp_url_key' => 'OPENSTACK_TEMP_URL_KEY', + 'openstack_auth_url' => 'https://auth.cloud.ovh.net/v2.0/', + 'openstack_region' => 'DE1', + 'openstack_tenant' => 'TENANT_ID', + } + ``` + +1. Save the file and [reconfigure GitLab][] for the changes to take effect. +1. Migrate any existing local uploads to the object storage using [`gitlab:uploads:migrate` rake task](raketasks/uploads/migrate.md). + +--- + +**In installations from source:** + +_The uploads are stored by default in +`/home/git/gitlab/public/uploads/-/system`._ + +1. Edit `/home/git/gitlab/config/gitlab.yml` and add or amend the following + lines: + + ```yaml + uploads: + object_store: + enabled: true + direct_upload: false + background_upload: true + proxy_download: false + remote_directory: OPENSTACK_OBJECT_CONTAINER_NAME + connection: + provider: OpenStack + openstack_username: OPENSTACK_USERNAME + openstack_api_key: OPENSTACK_PASSWORD + openstack_temp_url_key: OPENSTACK_TEMP_URL_KEY + openstack_auth_url: 'https://auth.cloud.ovh.net/v2.0/' + openstack_region: DE1 + openstack_tenant: 'TENANT_ID' + ``` + +1. Save the file and [reconfigure GitLab][] for the changes to take effect. +1. Migrate any existing local uploads to the object storage using [`gitlab:uploads:migrate` rake task](raketasks/uploads/migrate.md). + [reconfigure gitlab]: restart_gitlab.md#omnibus-gitlab-reconfigure "How to reconfigure Omnibus GitLab" [restart gitlab]: restart_gitlab.md#installations-from-source "How to restart GitLab" [eep]: https://about.gitlab.com/gitlab-ee/ "GitLab Premium" |
