opensearch-docs-cn/_api-reference/snapshots/create-repository.md

layout	title	parent	nav_order
default	Register Snapshot Repository	Snapshot APIs	1

Registering or updating a snapshot repository

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/my-first-repo/ 
PUT /_snapshot/my-first-repo/

Path parameters

Parameter	Data type	Description
repository	String	Repository name

Request parameters

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

fs repository

Request field	Description
location	The file system directory for snapshots, such as a mounted directory from a file server or a Samba share. Must be accessible by all nodes. Required.
chunk_size	Breaks large files into chunks during snapshot operations (e.g. 64mb, 1gb), which is important for cloud storage providers and far less important for shared file systems. Default is null (unlimited). Optional.
compress	Whether to compress metadata files. This setting does not affect data files, which might already be compressed, depending on your index settings. Default is false. Optional.
max_restore_bytes_per_sec	The maximum rate at which snapshots restore. Default is 40 MB per second (40m). Optional.
max_snapshot_bytes_per_sec	The maximum rate at which snapshots take. Default is 40 MB per second (40m). Optional.
readonly	Whether the repository is read-only. Useful when migrating from one cluster ("readonly": false when registering) to another cluster ("readonly": true when registering). Optional.

Example request

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"
  }
}

{% include copy-curl.html %}

s3 repository

Request field	Description
base_path	The path within the bucket in which you want to store snapshots (for example, my/snapshot/directory). Optional. If not specified, snapshots are stored in the S3 bucket root.
bucket	Name of the S3 bucket. Required.
buffer_size	The threshold beyond which chunks (of chunk_size) should be broken into pieces (of buffer_size) and sent to S3 using a different API. Default is the smaller of two values: 100 MB or 5% of the Java heap. Valid values are between 5mb and 5gb. We don't recommend changing this option.
canned_acl	S3 has several canned ACLs that the repository-s3 plugin can add to objects as it creates them in S3. Default is private. Optional.
chunk_size	Breaks files into chunks during snapshot operations (e.g. 64mb, 1gb), which is important for cloud storage providers and far less important for shared file systems. Default is 1gb. Optional.
client	When specifying client settings (e.g. s3.client.default.access_key), you can use a string other than default (e.g. s3.client.backup-role.access_key). If you used an alternate name, change this value to match. Default and recommended value is default. Optional.
compress	Whether to compress metadata files. This setting does not affect data files, which might already be compressed, depending on your index settings. Default is false. Optional.
max_restore_bytes_per_sec	The maximum rate at which snapshots restore. Default is 40 MB per second (40m). Optional.
max_snapshot_bytes_per_sec	The maximum rate at which snapshots take. Default is 40 MB per second (40m). Optional.
readonly	Whether the repository is read-only. Useful when migrating from one cluster ("readonly": false when registering) to another cluster ("readonly": true when registering). Optional.
server_side_encryption	Whether to encrypt snapshot files in the S3 bucket. This setting uses AES-256 with S3-managed keys. See Protecting data using server-side encryption. Default is false. Optional.
storage_class	Specifies the S3 storage class for the snapshots files. Default is standard. Do not use the glacier and deep_archive storage classes. Optional.

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. {: .note}

Example request

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"
  }
}

{% include copy-curl.html %}

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. {: .note}