IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.
« Snapshot and restore APIs Verify snapshot repository API »
Elastic Docs ›Elasticsearch Guide [7.16] ›REST APIs ›Snapshot and restore APIs

Create or update snapshot repository API

edit

Create or update snapshot repository API

edit

Registers or updates a snapshot repository.

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

Request

edit

PUT /_snapshot/<repository>

POST /_snapshot/<repository>

Prerequisites

edit
  • If the Elasticsearch security features are enabled, you must have the manage cluster privilege to use this API.
  • To register a snapshot repository, the cluster’s global metadata must be writeable. Ensure there aren’t any cluster blocks that prevent write access.

Path parameters

edit
<repository>
(Required, string) Name of the snapshot repository to register or update.

Query parameters

edit

Several options for this API can be specified using a query parameter or a request body parameter. If both parameters are specified, only the query parameter is used.

master_timeout
(Optional, time units) Specifies the period of time to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error. Defaults to 30s.
timeout
(Optional, time units) Specifies the period of time to wait for a response. If no response is received before the timeout expires, the request fails and returns an error. Defaults to 30s.
verify

(Optional, Boolean) If true, the request verifies the repository is functional on all master and data nodes in the cluster. If false, this verification is skipped. Defaults to true.

You can manually perform this verification using the verify snapshot repository API.

Request body

edit
type

(Required, string) Repository type.

Valid values for type
fs

Shared file system repository. Repositories of this type use a shared file system to store snapshots. This file system must accessible to all master and data nodes in the cluster.

To register a shared file system repository, you must mount the same shared filesystem to the same location on all master and data nodes. This location must be registered in the path.repo setting on all master and data nodes in the cluster.

See Shared file system repository.

source

Source-only repository. You can use source-only repositories to create minimal, source-only snapshots that take up to 50% less space on disk.

Source-only snapshots are only supported if the _source field is enabled and no source-filtering is applied.

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.

See Source-only repository.

url

URL repository. Repositories of this type are read-only for the cluster. This means the cluster can retrieve or restore snapshots from the repository but cannot write or create snapshots in it.

You can use URL repositories as an alternative way to give a cluster read-only access to a shared file system (fs) repository.

See Read-only URL repository.

More repository types are available through these official plugins:

settings

(Required, object) Contains settings for the repository.

The following settings properties are valid for all repository types:

Properties of settings
chunk_size
(Optional, byte value) Maximum size of files in snapshots. In snapshots, files larger than this are broken down into chunks of this size or smaller. Defaults to null (unlimited file size).
compress
(Optional, Boolean) If true, metadata files, such as index mappings and settings, are compressed in snapshots. Data files are not compressed. Defaults to true.
max_number_of_snapshots

(Optional, integer) Maximum number of snapshots the repository can contain. Defaults to 500.

We do not recommend increasing max_number_of_snapshots. Larger snapshot repositories may degrade master node performance and cause stability issues. Instead, delete older snapshots or use multiple repositories.

max_restore_bytes_per_sec
(Optional, byte value) Maximum snapshot restore rate per node. Defaults to unlimited. Note that restores are also throttled through recovery settings.
max_snapshot_bytes_per_sec
(Optional, byte value) Maximum snapshot creation rate per node. Defaults to 40mb per second.
readonly

(Optional, Boolean) If true, the repository is read-only. The cluster can retrieve and restore snapshots from the repository but not write to the repository or create snapshots in it.

If false, the cluster can write to the repository and create snapshots in it. Defaults to false.

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.

Only a cluster with write access can create snapshots in the repository. All other clusters connected to the repository should have the readonly parameter set to true. This means those clusters can retrieve or restore snapshots from the repository but not create snapshots in it.

Other accepted settings properties depend on the repository type, set using the type parameter.

Valid settings properties for fs repositories
location
(Required, string) Location of the shared filesystem used to store and retrieve snapshots. This location must be registered in the path.repo setting on all master and data nodes in the cluster.
Valid settings properties for source repositories
delegate_type

(Optional, string) Delegated repository type. For valid values, see the type parameter.

source repositories can use settings properties for its delegated repository type. See Source-only repository.

Valid settings properties for url repositories
url

(Required, string) URL location of the root of the shared filesystem repository. The following protocols are supported:

  • file
  • ftp
  • http
  • https
  • jar

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

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. You don’t need to register URLs using the ftp, http, https, or jar protocols in the path.repo setting. ---

http_max_retries
(Optional, integer) Maximum number of retries for http and https URLs. Defaults to 5.
http_socket_timeout
(Optional, time value) Maximum wait time for data transfers over a connection. Defaults to 50s.
verify

(Optional, Boolean) If true, the request verifies the repository is functional on all master and data nodes in the cluster. If false, this verification is skipped. Defaults to true.

You can manually perform this verification using the verify snapshot repository API.

« Snapshot and restore APIs Verify snapshot repository API »