diff options
Diffstat (limited to 'doc/administration/pages')
| -rw-r--r-- | doc/administration/pages/index.md | 125 | ||||
| -rw-r--r-- | doc/administration/pages/source.md | 2 |
2 files changed, 109 insertions, 18 deletions
diff --git a/doc/administration/pages/index.md b/doc/administration/pages/index.md index 9e949468805..655e35c3e60 100644 --- a/doc/administration/pages/index.md +++ b/doc/administration/pages/index.md @@ -190,7 +190,7 @@ outside world. ### Additional configuration for Docker container The GitLab Pages daemon doesn't have permissions to bind mounts when it runs -in a Docker container. To overcome this issue, you must change the chroot +in a Docker container. To overcome this issue, you must change the `chroot` behavior: 1. Edit `/etc/gitlab/gitlab.rb`. @@ -216,13 +216,13 @@ control over how the Pages daemon runs and serves content in your environment. | Setting | Description | | ------- | ----------- | -| `pages_external_url` | The URL where GitLab Pages is accessible, including protocol (HTTP / HTTPS). If `https://` is used, you must also set `gitlab_pages['ssl_certificate']` and `gitlab_pages['ssl_certificate_key']`. +| `pages_external_url` | The URL where GitLab Pages is accessible, including protocol (HTTP / HTTPS). If `https://` is used, additional configuration is required. See [Wildcard domains with TLS support](#wildcard-domains-with-tls-support) and [Custom domains with TLS support](#custom-domains-with-tls-support) for details. | `gitlab_pages[]` | | | `access_control` | Whether to enable [access control](index.md#access-control). | `api_secret_key` | Full path to file with secret key used to authenticate with the GitLab API. Auto-generated when left unset. | `artifacts_server` | Enable viewing [artifacts](../job_artifacts.md) in GitLab Pages. | `artifacts_server_timeout` | Timeout (in seconds) for a proxied request to the artifacts server. -| `artifacts_server_url` | API URL to proxy artifact requests to. Defaults to GitLab `external URL` + `/api/v4`, for example `https://gitlab.com/api/v4`. +| `artifacts_server_url` | API URL to proxy artifact requests to. Defaults to GitLab `external URL` + `/api/v4`, for example `https://gitlab.com/api/v4`. When running a [separate Pages server](#running-gitlab-pages-on-a-separate-server), this URL must point to the main GitLab server's API. | `auth_redirect_uri` | Callback URL for authenticating with GitLab. Defaults to project's subdomain of `pages_external_url` + `/auth`. | `auth_secret` | Secret key for signing authentication requests. Leave blank to pull automatically from GitLab during OAuth registration. | `dir` | Working directory for configuration and secrets files. @@ -234,9 +234,10 @@ control over how the Pages daemon runs and serves content in your environment. | `domain_config_source` | Domain configuration source (default: `auto`) | `gitlab_id` | The OAuth application public ID. Leave blank to automatically fill when Pages authenticates with GitLab. | `gitlab_secret` | The OAuth application secret. Leave blank to automatically fill when Pages authenticates with GitLab. +| `auth_scope` | The OAuth application scope to use for authentication. Must match GitLab Pages OAuth application settings. Leave blank to use `api` scope by default. | `gitlab_server` | Server to use for authentication when access control is enabled; defaults to GitLab `external_url`. | `headers` | Specify any additional http headers that should be sent to the client with each response. -| `inplace_chroot` | On [systems that don't support bind-mounts](index.md#additional-configuration-for-docker-container), this instructs GitLab Pages to chroot into its `pages_path` directory. Some caveats exist when using inplace chroot; refer to the GitLab Pages [README](https://gitlab.com/gitlab-org/gitlab-pages/blob/master/README.md#caveats) for more information. +| `inplace_chroot` | On [systems that don't support bind-mounts](index.md#additional-configuration-for-docker-container), this instructs GitLab Pages to `chroot` into its `pages_path` directory. Some caveats exist when using in-place `chroot`; refer to the GitLab Pages [README](https://gitlab.com/gitlab-org/gitlab-pages/blob/master/README.md#caveats) for more information. | `insecure_ciphers` | Use default list of cipher suites, may contain insecure ones like 3DES and RC4. | `internal_gitlab_server` | Internal GitLab server address used exclusively for API requests. Useful if you want to send that traffic over an internal load balancer. Defaults to GitLab `external_url`. | `listen_proxy` | The addresses to listen on for reverse-proxy requests. Pages binds to these addresses' network sockets and receives incoming requests from them. Sets the value of `proxy_pass` in `$nginx-dir/conf/gitlab-pages.conf`. @@ -400,6 +401,25 @@ NOTE: For this setting to be effective with multi-node setups, it has to be applied to all the App nodes and Sidekiq nodes. +#### Using Pages with reduced authentication scope + +By default, the Pages daemon uses the `api` scope to authenticate. You can configure this. For +example, this reduces the scope to `read_api` in `/etc/gitlab/gitlab.rb`: + +```ruby +gitlab_pages['auth_scope'] = 'read_api' +``` + +The scope to use for authentication must match the GitLab Pages OAuth application settings. Users of +pre-existing applications must modify the GitLab Pages OAuth application. Follow these steps to do +this: + +1. Navigate to your instance's **Admin Area > Settings > Applications** and expand **GitLab Pages** + settings. +1. Clear the `api` scope's checkbox and select the desired scope's checkbox (for example, + `read_api`). +1. Click **Save changes**. + #### Disabling public access to all Pages websites > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32095) in GitLab 12.7. @@ -538,7 +558,7 @@ the below steps to do a no downtime transfer to a new storage location. 1. [Reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure). 1. Verify Pages are still being served up as expected. -1. Unpause Pages deployments by removing from `/etc/gitlab/gitlab.rb` the `sidekiq` setting set above. +1. Resume Pages deployments by removing from `/etc/gitlab/gitlab.rb` the `sidekiq` setting set above. 1. [Reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure). 1. Trigger a new Pages deployment and verify it's working as expected. 1. Remove the old Pages storage location: `sudo rm -rf /var/opt/gitlab/gitlab-rails/shared/pages` @@ -573,7 +593,7 @@ You can configure the maximum size of the unpacked archive per project in **Admin Area > Settings > Preferences > Pages**, in **Maximum size of pages (MB)**. The default is 100MB. -### Override maximum pages size per project or group **(PREMIUM ONLY)** +### Override maximum pages size per project or group **(PREMIUM SELF)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/16610) in GitLab 12.7. @@ -629,7 +649,7 @@ database encryption. Proceed with caution. on the **Pages server** and configure this share to allow access from your main **GitLab server**. Note that the example there is more general and - shares several sub-directories from `/home` to several `/nfs/home` mountpoints. + shares several sub-directories from `/home` to several `/nfs/home` mount points. For our Pages-specific example here, we instead share only the default GitLab Pages folder `/var/opt/gitlab/gitlab-rails/shared/pages` from the **Pages server** and we mount it to `/mnt/pages` @@ -689,7 +709,7 @@ Pages server. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/217912) in GitLab 13.3. GitLab Pages can use different sources to get domain configuration. -The default value is `nil`. However, GitLab Pages defaults to `auto`. +The default value for Omnibus installations is `nil`. ```ruby gitlab_pages['domain_config_source'] = nil @@ -700,8 +720,33 @@ preferred source is `gitlab`, which uses [API-based configuration](#gitlab-api-b For more details see this [blog post](https://about.gitlab.com/blog/2020/08/03/how-gitlab-pages-uses-the-gitlab-api-to-serve-content/). +### Deprecated domain_config_source + +WARNING: +The flag `gitlab_pages['domain_config_source']` is deprecated for use in [GitLab 13.9](https://gitlab.com/gitlab-org/gitlab/-/issues/217913), +and is planned for removal in GitLab 14.0. + +GitLab 13.0 introduced the special flag `domain_config_source` to support manual opt-in to +[API-based configuration](#gitlab-api-based-configuration). +GitLab 13.7 introduced the [`auto` value](https://gitlab.com/gitlab-org/gitlab/-/issues/218358) +to support a smoother transition to API-based configuration. + +Starting with GitLab 14.0, GitLab Pages only supports API-based configuration, and +[disk source configuration is removed](https://gitlab.com/gitlab-org/gitlab-pages/-/issues/382). +Therefore, GitLab 14.0 also removes `domain_config_source`. + +GitLab Pages fails to start if it can't connect to the GitLab API. For other common issues, see the +[troubleshooting section](#failed-to-connect-to-the-internal-gitlab-api) +or report an issue. + ### GitLab API-based configuration +WARNING: +The flag `gitlab_pages['domain_config_source']` is deprecated for use in [GitLab 13.9](https://gitlab.com/gitlab-org/gitlab/-/issues/217913), +and is planned for removal in GitLab 14.0. In GitLab 14.0 and later, GitLab Pages attempts to +connect to the API automatically, without requiring the manual configuration steps shown here. Pages +fails to start if this automatic connection fails. + GitLab Pages can use an API-based configuration. This replaces disk source configuration, which was used prior to GitLab 13.0. Follow these steps to enable it: @@ -730,6 +775,13 @@ or report an issue. ### Object storage settings +WARNING: +With the following settings, Pages uses both NFS and Object Storage locations when deploying the +site. **Do not remove the existing NFS mount used by Pages** when applying these settings. For more +information, see the epics +[3901](https://gitlab.com/groups/gitlab-org/-/epics/3901#how-to-test-object-storage-integration-in-beta) +and [3910](https://gitlab.com/groups/gitlab-org/-/epics/3910). + The following settings are: - Nested under `pages:` and then `object_store:` on source installations. @@ -818,7 +870,7 @@ but commented out to help encourage others to add to it in the future. --> ### `open /etc/ssl/ca-bundle.pem: permission denied` -GitLab Pages runs inside a chroot jail, usually in a uniquely numbered directory like +GitLab Pages runs inside a `chroot` jail, usually in a uniquely numbered directory like `/tmp/gitlab-pages-*`. Within the jail, a bundle of trusted certificates is @@ -828,7 +880,7 @@ from `/opt/gitlab/embedded/ssl/certs/cacert.pem` as part of starting up Pages. If the permissions on the source file are incorrect (they should be `0644`), then -the file inside the chroot jail is also wrong. +the file inside the `chroot` jail is also wrong. Pages logs errors in `/var/log/gitlab/gitlab-pages/current` like: @@ -837,8 +889,8 @@ x509: failed to load system roots and no roots provided open /etc/ssl/ca-bundle.pem: permission denied ``` -The use of a chroot jail makes this error misleading, as it is not -referring to `/etc/ssl` on the root filesystem. +The use of a `chroot` jail makes this error misleading, as it is not +referring to `/etc/ssl` on the root file system. The fix is to correct the source file permissions and restart Pages: @@ -862,8 +914,8 @@ open /opt/gitlab/embedded/ssl/certs/cacert.pem: no such file or directory x509: certificate signed by unknown authority ``` -The reason for those errors is that the files `resolv.conf` and `ca-bundle.pem` are missing inside the chroot. -The fix is to copy the host's `/etc/resolv.conf` and the GitLab certificate bundle inside the chroot: +The reason for those errors is that the files `resolv.conf` and `ca-bundle.pem` are missing inside the `chroot`. +The fix is to copy the host's `/etc/resolv.conf` and the GitLab certificate bundle inside the `chroot`: ```shell sudo mkdir -p /var/opt/gitlab/gitlab-rails/shared/pages/etc/ssl @@ -895,7 +947,7 @@ gitlab_pages['listen_proxy'] = '127.0.0.1:8090' ### 404 error after transferring project to a different group or user If you encounter a `404 Not Found` error a Pages site after transferring a project to -another group or user, you must trigger adomain configuration update for Pages. To do +another group or user, you must trigger a domain configuration update for Pages. To do so, write something in the `.update` file. The Pages daemon monitors for changes to this file, and reloads the configuration when changes occur. @@ -928,11 +980,30 @@ For example, if there is a connection timeout: error="failed to connect to internal Pages API: Get \"https://gitlab.example.com:3000/api/v4/internal/pages/status\": net/http: request canceled while waiting for connection (Client.Timeout exceeded while awaiting headers)" ``` +### Pages cannot communicate with an instance of the GitLab API + +WARNING: +The flag `gitlab_pages['domain_config_source']` is [deprecated](#deprecated-domain_config_source) +for use in [GitLab 13.9](https://gitlab.com/gitlab-org/gitlab/-/issues/217913), +and is planned for removal in GitLab 14.0. + +If you use the default value for `domain_config_source=auto` and run multiple instances of GitLab +Pages, you may see intermittent 502 error responses while serving Pages content. You may also see +the following warning in the Pages logs: + +```plaintext +WARN[0010] Pages cannot communicate with an instance of the GitLab API. Please sync your gitlab-secrets.json file https://gitlab.com/gitlab-org/gitlab-pages/-/issues/535#workaround. error="pages endpoint unauthorized" +``` + +This can happen if your `gitlab-secrets.json` file is out of date between GitLab Rails and GitLab +Pages. Follow steps 8-10 of [Running GitLab Pages on a separate server](#running-gitlab-pages-on-a-separate-server), +in all of your GitLab Pages instances. + ### 500 error with `securecookie: failed to generate random iv` and `Failed to save the session` This problem most likely results from an [out-dated operating system](https://docs.gitlab.com/omnibus/package-information/deprecated_os.html). -The [Pages daemon uses the `securecookie` library](https://gitlab.com/search?group_id=9970&project_id=734943&repository_ref=master&scope=blobs&search=securecookie&snippets=false) to get random strings via [crypto/rand in Go](https://golang.org/pkg/crypto/rand/#pkg-variables). -This requires the `getrandom` syscall or `/dev/urandom` to be available on the host OS. +The [Pages daemon uses the `securecookie` library](https://gitlab.com/search?group_id=9970&project_id=734943&repository_ref=master&scope=blobs&search=securecookie&snippets=false) to get random strings via [`crypto/rand` in Go](https://golang.org/pkg/crypto/rand/#pkg-variables). +This requires the `getrandom` system call or `/dev/urandom` to be available on the host OS. Upgrading to an [officially supported operating system](https://about.gitlab.com/install/) is recommended. ### The requested scope is invalid, malformed, or unknown @@ -940,6 +1011,8 @@ Upgrading to an [officially supported operating system](https://about.gitlab.com This problem comes from the permissions of the GitLab Pages OAuth application. To fix it, go to **Admin > Applications > GitLab Pages** and edit the application. Under **Scopes**, ensure that the `api` scope is selected and save your changes. +When running a [separate Pages server](#running-gitlab-pages-on-a-separate-server), +this setting needs to be configured on the main GitLab server. ### Workaround in case no wildcard DNS entry can be set @@ -948,3 +1021,21 @@ If the wildcard DNS [prerequisite](#prerequisites) can't be met, you can still u 1. [Move](../../user/project/settings/index.md#transferring-an-existing-project-into-another-namespace) all projects you need to use Pages with into a single group namespace, for example `pages`. 1. Configure a [DNS entry](#dns-configuration) without the `*.`-wildcard, for example `pages.example.io`. + +### Pages daemon fails with permission denied errors + +If `/tmp` is mounted with `noexec`, the Pages daemon fails to start with an error like: + +```plaintext +{"error":"fork/exec /gitlab-pages: permission denied","level":"fatal","msg":"could not create pages daemon","time":"2021-02-02T21:54:34Z"} +``` + +In this case, change `TMPDIR` to a location that is not mounted with `noexec`. Add the following to +`/etc/gitlab/gitlab.rb`: + +```ruby +gitlab_pages['env'] = {'TMPDIR' => '<new_tmp_path>'} +``` + +Once added, reconfigure with `sudo gitlab-ctl reconfigure` and restart GitLab with +`sudo gitlab-ctl restart`. diff --git a/doc/administration/pages/source.md b/doc/administration/pages/source.md index 0aebeaf2ebe..d1a8b703860 100644 --- a/doc/administration/pages/source.md +++ b/doc/administration/pages/source.md @@ -407,7 +407,7 @@ Pages access control is disabled by default. To enable it: ``` 1. [Restart GitLab](../restart_gitlab.md#installations-from-source). -1. Create a new [system OAuth application](../../integration/oauth_provider.md#adding-an-application-through-the-profile). +1. Create a new [system OAuth application](../../integration/oauth_provider.md#add-an-application-through-the-profile). This should be called `GitLab Pages` and have a `Redirect URL` of `https://projects.example.io/auth`. It does not need to be a "trusted" application, but it does need the `api` scope. |