Register a snapshot repository

You must register a snapshot repository before you can perform snapshot and restore operations. Use the create or update snapshot repository API to register or update a snapshot repository. We recommend creating a new snapshot repository for each major version. The valid repository settings depend on the repository type.

If you register the same snapshot repository with multiple clusters, only one cluster should have write access to the repository. All other clusters connected to that repository should set the repository to readonly mode.

PUT /_snapshot/my_backup
{
  "type": "fs",
  "settings": {
    "location": "my_backup_location"
  }
}

Use the get snapshot API to retrieve information about a registered repository:

GET /_snapshot/my_backup

This request returns the following response:

{
  "my_backup": {
    "type": "fs",
    "uuid": "0JLknrXbSUiVPuLakHjBrQ",
    "settings": {
      "location": "my_backup_location"
    }
  }
}

To retrieve information about multiple repositories, specify a comma-delimited list of repositories. You can also use a wildcard (*) when specifying repository names. For example, the following request retrieves information about all of the snapshot repositories that start with repo or contain backup:

GET /_snapshot/repo*,*backup*

To retrieve information about all registered snapshot repositories, omit the repository name:

GET /_snapshot

Alternatively, you can specify _all:

GET /_snapshot/_all

You can unregister a repository using the delete snapshot repository API:

DELETE /_snapshot/my_backup

When a repository is unregistered, Elasticsearch only removes the reference to the location where the repository is storing the snapshots. The snapshots themselves are left untouched and in place.

Use a shared file system repository ("type": "fs") to store snapshots on a shared file system.

To register a shared file system repository, first mount the file system to the same location on all master and data nodes. Then add the file system’s path or parent directory to the path.repo setting in elasticsearch.yml for each master and data node. For running clusters, this requires a rolling restart of each node.

Supported path.repo values vary by platform:

path:
  repo:
    - /mount/backups
    - /mount/long_term_backups

PUT /_snapshot/my_fs_backup
{
  "type": "fs",
  "settings": {
    "location": "/mount/backups/my_fs_backup_location",
    "compress": true
  }
}

PUT /_snapshot/my_fs_backup
{
  "type": "fs",
  "settings": {
    "location": "my_fs_backup_location",       
    "compress": true
  }
}

path:
  repo:
    - "E:\\Mount\\Backups"                      
    - "\\\\MY_SERVER\\Mount\\Long_term_backups" 

PUT /_snapshot/my_fs_backup
{
  "type": "fs",
  "settings": {
    "location": "E:\\Mount\\Backups\\My_fs_backup_location",
    "compress": true
  }
}

PUT /_snapshot/my_fs_backup
{
  "type": "fs",
  "settings": {
    "location": "My_fs_backup_location",       
    "compress": true
  }
}

If you register the same snapshot repository with multiple clusters, only one cluster should have write access to the repository. Having multiple clusters write to the repository at the same time risks corrupting the contents of the repository.

To reduce this risk, you can use URL repositories ("type": "url") to give one or more clusters read-only access to a shared file system repository. As URL repositories are always read-only, they are a safer and more convenient alternative to registering a read-only shared filesystem repository.

The URL specified in the url parameter should point to the root of the shared filesystem repository.

PUT /_snapshot/my_read_only_url_repository
{
  "type": "url",
  "settings": {
    "url": "file:/mount/backups/my_fs_backup_location"
  }
}

The following settings are supported:

The url parameter supports the following protocols:

URLs using the file protocol must point to the location of a shared filesystem accessible to all master and data nodes in the cluster. This location must be registered in the path.repo setting, similar to a shared file system repository.

URLs using the ftp, http, or https protocols must be explicitly allowed with the repositories.url.allowed_urls setting. This setting supports wildcards (*) in place of a host, path, query, or fragment in the URL. For example:

repositories.url.allowed_urls: ["http://www.example.org/root/*", "https://*.mydomain.com/*?*#*"]

A source repository enables you to create minimal, source-only snapshots that take up to 50% less space on disk. Source only snapshots contain stored fields and index metadata. They do not include index or doc values structures and are not searchable when restored. After restoring a source-only snapshot, you must reindex the data into a new index.

Source repositories delegate to another snapshot repository for storage.

When you create a source repository, you must specify the type and name of the delegate repository where the snapshots will be stored:

PUT _snapshot/my_src_only_repository
{
  "type": "source",
  "settings": {
    "delegate_type": "fs",
    "location": "my_backup_location"
  }
}

Other repository backends are available in these official plugins:

When a repository is registered, it’s immediately verified on all master and data nodes to make sure that it is functional on all nodes currently present in the cluster. The verify parameter can be used to explicitly disable the repository verification when registering or updating a repository:

PUT /_snapshot/my_unverified_backup?verify=false
{
  "type": "fs",
  "settings": {
    "location": "my_unverified_backup_location"
  }
}

The verification process can also be executed manually by running the following command:

POST /_snapshot/my_unverified_backup/_verify

It returns a list of nodes where repository was successfully verified or an error message if verification process failed.

If desired, you can also test a repository more thoroughly using the Repository analysis API.

Repositories can over time accumulate data that is not referenced by any existing snapshot. This is a result of the data safety guarantees the snapshot functionality provides in failure scenarios during snapshot creation and the decentralized nature of the snapshot creation process. This unreferenced data does in no way negatively impact the performance or safety of a snapshot repository but leads to higher than necessary storage use. In order to clean up this unreferenced data, users can call the cleanup endpoint for a repository which will trigger a complete accounting of the repositories contents and subsequent deletion of all unreferenced data that was found.

POST /_snapshot/my_repository/_cleanup

The response to a cleanup request looks as follows:

{
  "results": {
    "deleted_bytes": 20,
    "deleted_blobs": 5
  }
}

Depending on the concrete repository implementation the numbers shown for bytes free as well as the number of blobs removed will either be an approximation or an exact result. Any non-zero value for the number of blobs removed implies that unreferenced blobs were found and subsequently cleaned up.

Please note that most of the cleanup operations executed by this endpoint are automatically executed when deleting any snapshot from a repository. If you regularly delete snapshots, you will in most cases not get any or only minor space savings from using this functionality and should lower your frequency of invoking it accordingly.

You may wish to make an independent backup of your repository, for instance so that you have an archive copy of its contents that you can use to recreate the repository in its current state at a later date.

You must ensure that Elasticsearch does not write to the repository while you are taking the backup of its contents. You can do this by unregistering it, or registering it with readonly: true, on all your clusters. If Elasticsearch writes any data to the repository during the backup then the contents of the backup may not be consistent and it may not be possible to recover any data from it in future.

Alternatively, if your repository supports it, you may take an atomic snapshot of the underlying filesystem and then take a backup of this filesystem snapshot. It is very important that the filesystem snapshot is taken atomically.

When restoring a repository from a backup, you must not register the repository with Elasticsearch until the repository contents are fully restored. If you alter the contents of a repository while it is registered with Elasticsearch then the repository may become unreadable or may silently lose some of its contents.