2020-06-03 16:04:07 +00:00
---
2022-09-21 18:19:11 +00:00
stage: Systems
2020-06-03 16:04:07 +00:00
group: Distribution
2023-12-05 03:40:46 +00:00
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments
2020-06-03 16:04:07 +00:00
---
2024-01-24 07:29:14 +00:00
# Backup
DETAILS:
**Tier:** Free, Premium, Ultimate
**Offering:** Self-managed
2015-07-14 11:55:42 +00:00
2023-08-02 06:46:52 +00:00
## Backup and restore configuration on a Linux package installation
2015-07-14 11:55:42 +00:00
2015-07-20 14:50:08 +00:00
It is recommended to keep a copy of `/etc/gitlab` , or at least of
`/etc/gitlab/gitlab-secrets.json` , in a safe place. If you ever
need to restore a GitLab application backup you need to also restore
`gitlab-secrets.json` . If you do not, GitLab users who are using
2016-04-15 22:09:15 +00:00
two-factor authentication will lose access to your GitLab server
2015-07-20 14:50:08 +00:00
and 'secure variables' stored in GitLab CI will be lost.
It is not recommended to store your configuration backup in the
2015-07-27 14:57:39 +00:00
same place as your application data backup, see below.
2015-07-20 14:50:08 +00:00
2023-08-02 06:46:52 +00:00
All configuration for Linux package installations is stored in `/etc/gitlab` . To backup your
2024-04-23 20:34:58 +00:00
configuration, just run `sudo gitlab-ctl backup-etc` . It creates a tar
2019-09-17 23:45:17 +00:00
archive in `/etc/gitlab/config_backup/` . Directory and backup files will be
readable only to root.
2015-07-14 11:55:42 +00:00
2020-12-08 08:16:05 +00:00
NOTE:
2021-05-13 05:18:05 +00:00
Running `sudo gitlab-ctl backup-etc --backup-path <DIRECTORY>` will place
2019-09-17 23:45:17 +00:00
the backup in the specified directory. The directory will be created if it
does not exist. Absolute paths are recommended.
2015-07-14 11:55:42 +00:00
2016-04-20 23:38:30 +00:00
To create a daily application backup, edit the cron table for user root:
```shell
sudo crontab -e -u root
```
The cron table will appear in an editor.
2021-06-03 16:20:36 +00:00
Enter the command to create a tar file containing the contents of
2020-03-18 06:38:21 +00:00
`/etc/gitlab/` . For example, schedule the backup to run every morning after a
2016-04-20 23:38:30 +00:00
weekday, Tuesday (day 2) through Saturday (day 6):
2020-04-06 06:05:25 +00:00
```plaintext
2019-09-17 23:45:17 +00:00
15 04 * * 2-6 gitlab-ctl backup-etc && cd /etc/gitlab/config_backup && cp $(ls -t | head -n1) /secret/gitlab/backups/
2016-04-20 23:38:30 +00:00
```
2021-06-17 09:28:13 +00:00
NOTE:
Make sure that `/secret/gitlab/backups/` exists.
2021-12-06 15:55:54 +00:00
You can extract the tar file as follows.
2015-07-14 11:55:42 +00:00
```shell
# Rename the existing /etc/gitlab, if any
sudo mv /etc/gitlab /etc/gitlab.$(date +%s)
# Change the example timestamp below for your configuration backup
2019-09-17 23:45:17 +00:00
sudo tar -xf gitlab_config_1487687824_2017_02_21.tar -C /
2015-07-14 11:55:42 +00:00
```
Remember to run `sudo gitlab-ctl reconfigure` after restoring a configuration
backup.
2020-12-08 08:16:05 +00:00
NOTE:
2020-08-10 02:37:54 +00:00
Your machines SSH host keys are stored in a separate location at `/etc/ssh/` . Be sure to also [backup and restore those keys ](https://superuser.com/questions/532040/copy-ssh-keys-from-one-server-to-another-server/532079#532079 ) to avoid man-in-the-middle attack warnings if you have to perform a full machine restore.
2015-07-14 11:55:42 +00:00
2021-05-13 05:18:05 +00:00
### Limit backup lifetime for configuration backups (prune old backups)
GitLab configuration backups can be pruned using the same `backup_keep_time` setting that is
2023-10-16 23:58:05 +00:00
[used for the GitLab application backups ](https://docs.gitlab.com/ee/administration/backup_restore/backup_gitlab.html#limit-backup-lifetime-for-local-files-prune-old-backups )
2021-05-13 05:18:05 +00:00
To make use of this setting, edit `/etc/gitlab/gitlab.rb` :
```ruby
## Limit backup lifetime to 7 days - 604800 seconds
gitlab_rails['backup_keep_time'] = 604800
```
The default `backup_keep_time` setting is `0` - which keeps all GitLab configuration and application backups.
Once a `backup_keep_time` is set - you can run `sudo gitlab-ctl backup-etc --delete-old-backups` to prune all
backups older than the current time minus the `backup_keep_time` .
You can provide the parameter `--no-delete-old-backups` if you want to keep all existing backups.
WARNING:
2021-05-31 12:46:34 +00:00
If no parameter is provided the default is `--delete-old-backups` , which will delete any backups
older than the current time minus the `backup_keep_time` , if `backup_keep_time` is greater than 0.
2021-05-13 05:18:05 +00:00
2017-04-25 09:55:13 +00:00
### Separate configuration backups from application data
2015-07-20 14:50:08 +00:00
Do not store your GitLab application backups (Git repositories, SQL
data) in the same place as your configuration backup (`/etc/gitlab`).
The `gitlab-secrets.json` file (and possibly also the `gitlab.rb`
file) contain database encryption keys to protect sensitive data
in the SQL database:
- GitLab two-factor authentication (2FA) user secrets ('QR codes')
- GitLab CI 'secure variables'
2016-04-15 22:35:51 +00:00
If you separate your configuration backup from your application data backup,
2016-11-17 10:55:20 +00:00
you reduce the chance that your encrypted application data will be
2016-04-15 22:35:51 +00:00
lost/leaked/stolen together with the keys needed to decrypt it.
2015-07-14 11:55:42 +00:00
2017-04-25 09:55:13 +00:00
## Creating an application backup
2015-07-14 11:55:42 +00:00
2016-04-15 22:35:51 +00:00
To create a backup of your repositories and GitLab metadata, follow the
2023-10-16 23:58:05 +00:00
[backup create documentation ](https://docs.gitlab.com/ee/administration/backup_restore/backup_gitlab.html ).
2015-07-14 11:55:42 +00:00
Backup create will store a tar file in `/var/opt/gitlab/backups` .
If you want to store your GitLab backups in a different directory, add the
following setting to `/etc/gitlab/gitlab.rb` and run `sudo gitlab-ctl
reconfigure`:
```ruby
gitlab_rails['backup_path'] = '/mnt/backups'
```
2017-04-25 09:55:13 +00:00
## Creating backups for GitLab instances in Docker containers
2016-10-21 18:32:06 +00:00
2021-07-07 16:20:16 +00:00
WARNING:
2023-10-16 23:58:05 +00:00
The backup command requires [additional parameters ](https://docs.gitlab.com/ee/administration/backup_restore/backup_gitlab.html#back-up-and-restore-for-installations-using-pgbouncer )
2021-07-07 16:20:16 +00:00
when your installation is using PgBouncer, for either performance reasons or when using it with a Patroni cluster.
2018-02-12 22:33:36 +00:00
Backups can be scheduled on the host by prepending `docker exec -t <your container name>` to the commands.
2016-10-21 18:32:06 +00:00
Backup application:
2016-10-24 14:32:45 +00:00
2016-10-21 18:32:06 +00:00
```shell
2019-07-29 09:02:40 +00:00
docker exec -t < your container name > gitlab-backup
2016-10-21 18:32:06 +00:00
```
2016-10-24 14:32:45 +00:00
2016-10-21 18:32:06 +00:00
Backup configuration and secrets:
2016-10-24 14:32:45 +00:00
2016-10-21 18:32:06 +00:00
```shell
2021-06-17 09:28:13 +00:00
docker exec -t < your container name > /bin/sh -c 'gitlab-ctl backup-etc & & cd /etc/gitlab/config_backup & & cp $(ls -t | head -n1) /secret/gitlab/backups/'
2016-10-21 18:32:06 +00:00
```
2020-12-08 08:16:05 +00:00
NOTE:
2020-10-28 19:26:12 +00:00
To persist these backups outside the container, mount volumes in the following directories:
1. `/secret/gitlab/backups` .
2021-06-28 10:28:47 +00:00
1. `/var/opt/gitlab` for [all application data ](https://docs.gitlab.com/ee/install/docker.html#set-up-the-volumes-location ), which includes backups.
2020-10-28 19:26:12 +00:00
1. `/var/opt/gitlab/backups` (optional). The `gitlab-backup` tool writes to this directory [by default ](#creating-an-application-backup ).
While this directory is nested inside `/var/opt/gitlab` , [Docker sorts these mounts ](https://github.com/moby/moby/pull/8055 ), allowing them to work in harmony.
This configuration enables, for example:
- Application data on regular local storage (through the second mount).
- A backup volume on network storage (through the third mount).
2016-10-21 18:32:06 +00:00
2017-04-25 09:55:13 +00:00
## Restoring an application backup
2015-07-14 11:55:42 +00:00
2023-10-16 23:58:05 +00:00
See [restore documentation ](https://docs.gitlab.com/ee/administration/backup_restore/restore_gitlab.html ).
2015-07-14 11:55:42 +00:00
2017-04-25 09:55:13 +00:00
## Backup and restore using non-packaged database
2015-07-14 11:55:42 +00:00
2017-02-15 19:35:03 +00:00
If you are using non-packaged database see [documentation on using non-packaged database ](database.md#using-a-non-packaged-postgresql-database-management-server ).
2015-07-14 11:55:42 +00:00
2017-04-25 09:55:13 +00:00
## Upload backups to remote (cloud) storage
2015-07-14 11:55:42 +00:00
2023-10-16 23:58:05 +00:00
For details check [backup documentation ](https://docs.gitlab.com/ee/administration/backup_restore/backup_gitlab.html#upload-backups-to-a-remote-cloud-storage ).
2015-09-18 14:23:58 +00:00
2017-04-25 09:55:13 +00:00
## Manually manage backup directory
2015-09-18 14:23:58 +00:00
2023-08-02 06:46:52 +00:00
Linux package installations create the backup directory set with `gitlab_rails['backup_path']` . The directory is owned by the user that is running GitLab and it has strict permissions set to be accessible to only that user.
2015-09-18 14:23:58 +00:00
That directory will hold backup archives and they contain sensitive information.
In some organizations permissions need to be different because of, for example, shipping the backup archives offsite.
To disable backup directory management, in `/etc/gitlab/gitlab.rb` set:
```ruby
gitlab_rails['manage_backup_path'] = false
```
2019-07-23 00:05:09 +00:00
2021-12-06 15:55:54 +00:00
WARNING:
If you set this configuration option, it is up to you to create the directory specified in `gitlab_rails['backup_path']` and to set permissions
2015-09-18 14:23:58 +00:00
which will allow user specified in `user['username']` to have correct access. Failing to do so will prevent GitLab from creating the backup archive.