You're viewing version 2.17 of the OpenSearch documentation. This version is no longer maintained. For the latest version, see the current documentation. For information about OpenSearch version maintenance, see Release Schedule and Maintenance Policy.

Registering or updating a snapshot repository

Introduced 1.0

You can register a new repository in which to store snapshots or update information for an existing repository by using the snapshots API.

There are two types of snapshot repositories:

• File system (fs): For instructions on creating an fs repository, see Register repository shared file system.

• Amazon Simple Storage Service (Amazon S3) bucket (s3): For instructions on creating an s3 repository, see Register repository Amazon S3.

For instructions on creating a repository, see Register repository.

Path and HTTP methods

POST /_snapshot/<repository>/ 
PUT /_snapshot/<repository>/

Path parameters

Request parameters

Request parameters depend on the type of repository: fs or s3.

Common parameters

The following table lists parameters that can be used with both the fs and s3 repositories.

shard_path_type values

The following values are supported in the shard_path_type setting:

• FIXED: Keeps the path structure in the existing hierarchical manner, such as <ROOT>/<BASE_PATH>/indices/<index-id>/0/<SHARD_BLOBS>.
• HASHED_PREFIX: Prepends a hashed prefix at the start of the path for each unique shard ID, for example, <ROOT>/<HASH-OF-INDEX-ID-AND-SHARD-ID>/<BASE_PATH>/indices/<index-id>/0/<SHARD_BLOBS>.
• HASHED_INFIX: Appends a hashed prefix after the base path for each unique shard ID, for example, <ROOT>/<BASE-PATH>/<HASH-OF-INDEX-ID-AND-SHARD-ID>/indices/<index-id>/0/<SHARD_BLOBS>. The hash method used is FNV_1A_COMPOSITE_1, which uses the FNV1a hash function and generates a custom-encoded 64-bit hash value that scales well with most remote store options. FNV1a takes the most significant 6 bits to create a URL-safe Base64 character and the next 14 bits to create a binary string.

fs repository

s3 repository

For the base_path parameter, do not enter the s3:// prefix when entering your S3 bucket details. Only the name of the bucket is required.

Example requests

fs

The following example registers an fs repository using the local directory /mnt/snapshots as location:

PUT /_snapshot/my-fs-repository
{
  "type": "fs",
  "settings": {
    "location": "/mnt/snapshots"
  }
}

s3

The following request registers a new S3 repository called my-opensearch-repo in an existing bucket called my-open-search-bucket. By default, all snapshots are stored in the my/snapshot/directory:

PUT /_snapshot/my-opensearch-repo
{
  "type": "s3",
  "settings": {
    "bucket": "my-open-search-bucket",
    "base_path": "my/snapshot/directory"
  }
}

Example response

Upon success, the following JSON object is returned:

{
  "acknowledged": true
}

To verify that the repository was registered, use the Get snapshot repository API, passing the repository name as the repository path parameter.