diff options
Diffstat (limited to 'doc/user/admin_area/license.md')
| -rw-r--r-- | doc/user/admin_area/license.md | 224 |
1 files changed, 115 insertions, 109 deletions
diff --git a/doc/user/admin_area/license.md b/doc/user/admin_area/license.md index d984f6f4092..c3f0c94db21 100644 --- a/doc/user/admin_area/license.md +++ b/doc/user/admin_area/license.md @@ -2,173 +2,179 @@ stage: Growth group: Conversion 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: howto --- -# Activating GitLab EE **(PREMIUM SELF)** +# Activate GitLab Enterprise Edition (EE) **(PREMIUM SELF)** -To enable features of GitLab Enterprise Edition (EE), you need to activate your instance. Ensure you are running an enterprise edition. To verify, sign in to GitLab and browse to `/help`. The GitLab edition and version are listed at the top of the **Help** page. +When you install a new GitLab instance without a license, it only has the Free features +enabled. To enable all features of GitLab Enterprise Edition (EE), activate +your instance with an activation code or a license file. When [the license expires](#what-happens-when-your-license-expires), +some functionality is locked. -If you are running GitLab Community Edition (CE), upgrade your installation to GitLab Enterprise Edition (EE). For more details, see [Upgrading between editions](../../update/index.md#upgrading-between-editions). If you have questions or need assistance upgrading from GitLab CE to EE please [contact GitLab Support](https://about.gitlab.com/support/#contact-support). +## Verify your GitLab edition -As of GitLab Enterprise Edition 9.4.0, a newly-installed instance without an -uploaded license only has the Free features active. A trial license activates all Ultimate features, but after [the trial expires](#what-happens-when-your-license-expires), some functionality -is locked. +To activate your instance, make sure you are running GitLab Enterprise Edition (EE). -## Activate GitLab EE with an Activation Code +To verify the edition, sign in to GitLab and select +**Help** (**{question-o}**) > **Help**. The GitLab edition and version are listed +at the top of the page. -As of GitLab Enterprise Edition 14.1, you need an activation code to activate your instance. You can obtain an activation code by [purchasing a license](https://about.gitlab.com/pricing/) or by signing up for a [free trial](https://about.gitlab.com/free-trial/). This activation code is a 24-character alphanumeric string you receive in a confirmation email. You can also sign in to the [Customers Portal](https://customers.gitlab.com/customers/sign_in) to copy the activation code to your clipboard. +If you are running GitLab Community Edition (CE), upgrade your installation to GitLab +EE. For more details, see [Upgrading between editions](../../update/index.md#upgrading-between-editions). +If you have questions or need assistance upgrading from GitLab CE to EE, +[contact GitLab Support](https://about.gitlab.com/support/#contact-support). -To begin the activation process with your activation code: +## Activate GitLab EE with an activation code + +In GitLab Enterprise Edition 14.1 and later, you need an activation code to activate +your instance. To get an activation code, [purchase a license](https://about.gitlab.com/pricing/) +or sign up for a [free trial](https://about.gitlab.com/free-trial/). The activation +code is a 24-character alphanumeric string you receive in a confirmation email. +You can also sign in to the [Customers Portal](https://customers.gitlab.com/customers/sign_in) +to copy the activation code to your clipboard. + +To activate your instance with an activation code: 1. Sign in to your GitLab self-managed instance. -1. From the top menu, select the Admin Area **{admin}**. -1. From the left sidebar, select **Subscription**. -1. Paste the activation code onto the input field. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Subscription**. +1. Enter the activation code in **Activation code**. 1. Read and accept the terms of service. 1. Select **Activate**. -## Activate GitLab EE with a License File - -If you receive a license file from GitLab (for example a new trial), you can upload it by signing into your GitLab instance as an administrator or adding it during installation. The license is a base64-encoded ASCII text file with a `.gitlab-license` extension. +## Activate GitLab EE with a license file -## Uploading your license +If you receive a license file from GitLab (for example, for a trial), you can +upload it to your instance or add it during installation. The license file is +a base64-encoded ASCII text file with a `.gitlab-license` extension. -The first time you visit your GitLab EE installation signed in as an administrator, -you should see a note urging you to upload a license with a link that takes you -to the **Subscription** area. +## Upload your license -Otherwise, to manually go to the **Subscription** area: - -1. Sign in to your GitLab self-managed instance. -1. From the top menu, select the Admin Area **{admin}**. -1. From the left sidebar, select **Subscription**, and select **Upload a license file**. +The first time you sign in to your GitLab instance, a note with a +link to the **Upload license** page should be displayed. - - *If you've received a `.gitlab-license` file:* - 1. Download the license file to your local machine. - 1. Select **Upload `.gitlab-license` file**. - 1. Select **Choose file** and select the license file. - In this example the license file is named `GitLab.gitlab-license`. - 1. Select the **Terms of Service** checkbox. - 1. Select **Upload License**. +Otherwise, to upload your license: -  +1. Sign in to GitLab as an administrator. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Settings**. +1. In the **License file** area, select **Upload a license**. +1. Upload a license: + - For a file, select **Upload `.gitlab-license` file**, **Choose file**, and + select the license file from your local machine. + - For plain text, select **Enter license key** and paste the contents in + **License key**. +1. Select the **Terms of Service** checkbox. +1. Select **Upload License**. - - *If you've received your license as plain text:* - 1. Select **Enter license key**. - 1. Copy the license and paste it into the **License key** field. - 1. Select the **Terms of Service** checkbox. - 1. Select **Upload License**. +## Add your license during installation -## Add your license at install time +You can import a license file when you install GitLab. -A license can be automatically imported at install time by placing a file named -`Gitlab.gitlab-license` in `/etc/gitlab/` for Omnibus GitLab, or `config/` for source installations. +- **For installations from source** + - Place the `Gitlab.gitlab-license` file in the `config/` directory. + - To specify a custom location and filename for the license, set the + `GITLAB_LICENSE_FILE` environment variable with the path to the file: -You can also specify a custom location and filename for the license: + ```shell + export GITLAB_LICENSE_FILE="/path/to/license/file" + ``` -- Source installations should set the `GITLAB_LICENSE_FILE` environment - variable with the path to a valid GitLab Enterprise Edition license. +- **For Omnibus package** + - Place the `Gitlab.gitlab-license` file in the `/etc/gitlab/` directory. + - To specify a custom location and filename for the license, add this entry to `gitlab.rb`: - ```shell - export GITLAB_LICENSE_FILE="/path/to/license/file" - ``` - -- Omnibus GitLab installations should add this entry to `gitlab.rb`: - - ```ruby - gitlab_rails['initial_license_file'] = "/path/to/license/file" - ``` + ```ruby + gitlab_rails['initial_license_file'] = "/path/to/license/file" + ``` WARNING: -These methods only add a license at the time of installation. Use the -**{admin}** **Admin Area** in the web user interface to renew or upgrade licenses. - ---- - -After the license is uploaded, all GitLab Enterprise Edition functionality -is active until the end of the license period. When that period ends, the -instance will [fall back](#what-happens-when-your-license-expires) to Free-only -functionality. - -You can review the license details at any time by going to **Admin Area > Subscription**. - -## Notification before the license expires - -One month before the license expires, a message informing about the expiration -date is displayed to GitLab administrators. Make sure that you update your -license, otherwise you miss all the paid features if your license expires. +These methods only add a license at the time of installation. To renew or upgrade +a license, upload the license in the **Admin Area** in the web user interface. ## What happens when your license expires -When your license expires, GitLab locks down features, like Git pushes -and issue creation. Then, your instance becomes read-only and -an expiration message is displayed to all administrators. +Fifteen days before the license expires, a notification banner with the upcoming expiration +date displays to GitLab administrators. -For GitLab self-managed instances, you have a 14-day grace period +When your license expires, GitLab locks features, like Git pushes +and issue creation. Your instance becomes read-only and +an expiration message displays to all administrators. You have a 14-day grace period before this occurs. -- To resume functionality, upload a new license. -- To fall back to Free features, delete all expired licenses. +To resume functionality, [upload a new license](#upload-your-license). -### Remove a license file +To go back to Free features, [delete all expired licenses](#remove-a-license-file). + +## Remove a license file To remove a license file from a self-managed instance: -1. From the top menu, select the Admin Area **{admin}**. -1. From the left sidebar, select **Subscription**. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Subscription**. 1. Select **Remove license**. -These steps may need to be repeated to completely remove all licenses, including those applied in the past. +Repeat these steps to remove all licenses, including those applied in the past. + +## View license details and history -## License history +To view your license details: -You can upload and view more than one license, but only the latest license in the current date -range is used as the active license. +1. On the top bar, select **Menu > Admin**. +1. On the left sidebar, select **Subscription**. + +You can upload and view more than one license, but only the latest license in +the current date range is the active license. When you upload a future-dated license, it doesn't take effect until its applicable date. -You can view all of your active subscriptions in the **Subscription history** table. +You can view all active subscriptions in the **Subscription history** table. NOTE: -In GitLab 13.6 and earlier, a notification banner about an expiring license may continue to be displayed even after a new license has been uploaded. -This happens when the newly uploaded license's start date is in the future and the expiring one is still active. +In GitLab 13.6 and earlier, a banner about an expiring license may continue to display +when you upload a new license. This happens when the start date of the new license +is in the future and the expiring one is still active. The banner disappears after the new license becomes active. ## Troubleshooting -### There is no Subscription tab in the Admin Area +### No Subscription area in the Admin Area -If you originally installed Community Edition rather than Enterprise Edition you must -[upgrade to Enterprise Edition](../../update/index.md#community-to-enterprise-edition) -before uploading your license. +You cannot upload your license because there is no **Subscription** area. +This issue might occur if: -GitLab.com users can't upload and use a self-managed license. If you -want to use paid features on GitLab.com, you can -[purchase a separate subscription](../../subscriptions/gitlab_com/index.md). +- You're running GitLab Community Edition. Before you upload your license, you + must [upgrade to Enterprise Edition](../../update/index.md#community-to-enterprise-edition). +- You're using GitLab.com. You cannot upload a self-managed license to GitLab.com. + To use paid features on GitLab.com, [purchase a separate subscription](../../subscriptions/gitlab_com/index.md). ### Users exceed license limit upon renewal -If you've added new users to your GitLab instance prior to renewal, you may need to -purchase additional seats to cover those users. If this is the case, and a license -without enough users is uploaded, GitLab displays a message prompting you to purchase -additional users. More information on how to determine the required number of users -and how to add additional seats can be found in the -[licensing FAQ](https://about.gitlab.com/pricing/licensing-faq/). +GitLab displays a message prompting you to purchase +additional users. This issue occurs if you upload a license that does not have enough +users to cover the number of users in your instance. + +To fix this issue, purchase additional seats to cover those users. +For more information, read the [licensing FAQ](https://about.gitlab.com/pricing/licensing-faq/). -In GitLab 14.2 and later, for instances that use a license file, you can exceed the number of purchased users and still activate your license. +In GitLab 14.2 and later, for instances that use a license file, the following +rules apply: -- If the users over license are less than or equal to 10% of the users in the subscription, - the license is applied and the overage is paid in the next true-up. -- If the users over license are more than 10% of the users in the subscription, +- If the users over license are less than or equal to 10% of the users in the license + file, the license is applied and you pay the overage in the next renewal. +- If the users over license are more than 10% of the users in the license file, you cannot apply the license without purchasing more users. -For example, if you purchased a license for 100 users, you can have 110 users when you activate -your license. However, if you have 111, you must purchase more users before you can activate. +For example, if you purchase a license for 100 users, you can have 110 users when you activate +your license. However, if you have 111 users, you must purchase more users before you can activate +the license. -### There is a connectivity issue +### Cannot activate instance due to connectivity error -In GitLab 14.1 and later, to activate your subscription, your GitLab instance must be connected to the internet. +In GitLab 14.1 and later, to activate your subscription with an activation code, +your GitLab instance must be connected to the internet. -If you have an offline or airgapped environment, you can [upload a license file](license.md#activate-gitlab-ee-with-a-license-file) instead. +If you have an offline or airgapped environment, +[upload a license file](license.md#activate-gitlab-ee-with-a-license-file) instead. -If you have questions or need assistance activating your instance, please [contact GitLab Support](https://about.gitlab.com/support/#contact-support). +If you have questions or need assistance activating your instance, +[contact GitLab Support](https://about.gitlab.com/support/#contact-support). |