<commit_before>[[modules-snapshots]]
== Snapshot And Restore

The snapshot and restore module allows to create snapshots of individual indices or an entire cluster into a remote
repository. At the time of the initial release only shared file system repository was supported, but now a range of
backends are available via officially supported repository plugins.

[float]
=== Repositories

Before any snapshot or restore operation can be performed a snapshot repository should be registered in
Elasticsearch. The following command registers a shared file system repository with the name `my_backup` that
will use location `/mount/backups/my_backup` to store snapshots.

[source,js]
-----------------------------------
$ curl -XPUT 'http://localhost:9200/_snapshot/my_backup' -d '{
    "type": "fs",
    "settings": {
        "location": "/mount/backups/my_backup",
        "compress": true
    }
}'
-----------------------------------

Once repository is registered, its information can be obtained using the following command:

[source,js]
-----------------------------------
$ curl -XGET 'http://localhost:9200/_snapshot/my_backup?pretty'
-----------------------------------
[source,js]
-----------------------------------
{
  "my_backup" : {
    "type" : "fs",
    "settings" : {
      "compress" : "true",
      "location" : "/mount/backups/my_backup"
    }
  }
}
-----------------------------------

If a repository name is not specified, or `_all` is used as repository name Elasticsearch will return information about
all repositories currently registered in the cluster:

[source,js]
-----------------------------------
$ curl -XGET 'http://localhost:9200/_snapshot'
-----------------------------------

or

[source,js]
-----------------------------------
$ curl -XGET 'http://localhost:9200/_snapshot/_all'
-----------------------------------

[float]
===== Shared File System Repository

The shared file system repository (`"type": "fs"`) is using shared file system to store snapshot. The path
specified in the `location` parameter should point to the same location in the shared filesystem and be accessible
on all data and master nodes. The following settings are supported:

[horizontal]
`location`:: Location of the snapshots. Mandatory.
`compress`:: Turns on compression of the snapshot files. Compression is applied only to metadata files (index mapping and settings). Data files are not compressed. Defaults to `true`.
`chunk_size`:: Big files can be broken down into chunks during snapshotting if needed. The chunk size can be specified in bytes or by
 using size value notation, i.e. 1g, 10m, 5k. Defaults to `null` (unlimited chunk size).
`verify`:: Verify repository upon creation. Defaults to `true`.

[float]
===== Read-only URL Repository

The URL repository (`"type": "url"`) can be used as an alternative read-only way to access data created by shared file
system repository  is using shared file system to store snapshot. The URL specified in the `url` parameter should
point to the root of the shared filesystem repository. The following settings are supported:

[horizontal]
`url`:: Location of the snapshots. Mandatory.

[float]
===== Common Repository Settings

The following are common settings applicable for all repository types:

[horizontal]
`max_restore_bytes_per_sec`:: Throttles per node restore rate. Defaults to `20mb` per second.
`max_snapshot_bytes_per_sec`:: Throttles per node snapshot rate. Defaults to `20mb` per second.


[float]
===== Repository plugins

Other repository backends are available in these official plugins:

* https://github.com/elasticsearch/elasticsearch-cloud-aws#s3-repository[AWS Cloud Plugin] for S3 repositories
* https://github.com/elasticsearch/elasticsearch-hadoop/tree/master/repository-hdfs[HDFS Plugin] for Hadoop environments
* https://github.com/elasticsearch/elasticsearch-cloud-azure#azure-repository[Azure Cloud Plugin] for Azure storage repositories


===== Repository Verification
added[1.4.0]

When repository is registered, it's immediately verified on all master and data nodes to make sure that it's functional
on all nodes currently present in the cluster. The verification process can also be executed manually by running the
following command:

[source,js]
-----------------------------------
$ curl -XPOST 'http://localhost:9200/_snapshot/my_backup/_verify'
-----------------------------------

It returns a list of nodes

[float]
=== Snapshot

A repository can contain multiple snapshots of the same cluster. Snapshot are identified by unique names within the
cluster. A snapshot with the name `snapshot_1` in the repository `my_backup` can be created by executing the following
command:

[source,js]
-----------------------------------
$ curl -XPUT "localhost:9200/_snapshot/my_backup/snapshot_1?wait_for_completion=true"
-----------------------------------<commit_msg>Docs: fix formatting in snapshots documentation<commit_after>[[modules-snapshots]]
== Snapshot And Restore

The snapshot and restore module allows to create snapshots of individual indices or an entire cluster into a remote
repository. At the time of the initial release only shared file system repository was supported, but now a range of
backends are available via officially supported repository plugins.

[float]
=== Repositories

Before any snapshot or restore operation can be performed a snapshot repository should be registered in
Elasticsearch. The following command registers a shared file system repository with the name `my_backup` that
will use location `/mount/backups/my_backup` to store snapshots.

[source,js]
-----------------------------------
$ curl -XPUT 'http://localhost:9200/_snapshot/my_backup' -d '{
    "type": "fs",
    "settings": {
        "location": "/mount/backups/my_backup",
        "compress": true
    }
}'
-----------------------------------

Once repository is registered, its information can be obtained using the following command:

[source,js]
-----------------------------------
$ curl -XGET 'http://localhost:9200/_snapshot/my_backup?pretty'
-----------------------------------
[source,js]
-----------------------------------
{
  "my_backup" : {
    "type" : "fs",
    "settings" : {
      "compress" : "true",
      "location" : "/mount/backups/my_backup"
    }
  }
}
-----------------------------------

If a repository name is not specified, or `_all` is used as repository name Elasticsearch will return information about
all repositories currently registered in the cluster:

[source,js]
-----------------------------------
$ curl -XGET 'http://localhost:9200/_snapshot'
-----------------------------------

or

[source,js]
-----------------------------------
$ curl -XGET 'http://localhost:9200/_snapshot/_all'
-----------------------------------

[float]
===== Shared File System Repository

The shared file system repository (`"type": "fs"`) is using shared file system to store snapshot. The path
specified in the `location` parameter should point to the same location in the shared filesystem and be accessible
on all data and master nodes. The following settings are supported:

[horizontal]
`location`:: Location of the snapshots. Mandatory.
`compress`:: Turns on compression of the snapshot files. Compression is applied only to metadata files (index mapping and settings). Data files are not compressed. Defaults to `true`.
`chunk_size`:: Big files can be broken down into chunks during snapshotting if needed. The chunk size can be specified in bytes or by
 using size value notation, i.e. 1g, 10m, 5k. Defaults to `null` (unlimited chunk size).
`verify`:: Verify repository upon creation. Defaults to `true`.

[float]
===== Read-only URL Repository

The URL repository (`"type": "url"`) can be used as an alternative read-only way to access data created by shared file
system repository  is using shared file system to store snapshot. The URL specified in the `url` parameter should
point to the root of the shared filesystem repository. The following settings are supported:

[horizontal]
`url`:: Location of the snapshots. Mandatory.

[float]
===== Common Repository Settings

The following are common settings applicable for all repository types:

[horizontal]
`max_restore_bytes_per_sec`:: Throttles per node restore rate. Defaults to `20mb` per second.
`max_snapshot_bytes_per_sec`:: Throttles per node snapshot rate. Defaults to `20mb` per second.


[float]
===== Repository plugins

Other repository backends are available in these official plugins:

* https://github.com/elasticsearch/elasticsearch-cloud-aws#s3-repository[AWS Cloud Plugin] for S3 repositories
* https://github.com/elasticsearch/elasticsearch-hadoop/tree/master/repository-hdfs[HDFS Plugin] for Hadoop environments
* https://github.com/elasticsearch/elasticsearch-cloud-azure#azure-repository[Azure Cloud Plugin] for Azure storage repositories

[float]
===== Repository Verification
added[1.4.0]

When repository is registered, it's immediately verified on all master and data nodes to make sure that it's functional
on all nodes currently present in the cluster. The verification process can also be executed manually by running the
following command:

[source,js]
-----------------------------------
$ curl -XPOST 'http://localhost:9200/_snapshot/my_backup/_verify'
-----------------------------------

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

[float]
=== Snapshot

A repository can contain multiple snapshots of the same cluster. Snapshot are identified by unique names within the
cluster. A snapshot with the name `snapshot_1` in the repository `my_backup` can be created by executing the following
command:

[source,js]
-----------------------------------
$ curl -XPUT "localhost:9200/_snapshot/my_backup/snapshot_1?wait_for_completion=true"
-----------------------------------
{'fraction_non_alphanumeric': 0.1750152098965727, 'fraction_numerical': 0.007909146217805718, 'mean_word_length': 2.932615629984051, 'pattern_counts': {'":': 12, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 6, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4320196', 'n_tokens_mistral': 2447, 'n_tokens_neox': 2388, 'n_words': 1059}