<commit_before>[[repository-s3]]
=== S3 Repository Plugin

The S3 repository plugin adds support for using AWS S3 as a repository for
{ref}/modules-snapshots.html[Snapshot/Restore].

*If you are looking for a hosted solution of Elasticsearch on AWS, please visit
https://www.elastic.co/cloud/.*

:plugin_name: repository-s3
include::install_remove.asciidoc[]

[[repository-s3-usage]]
==== Getting Started

The plugin provides a repository type named `s3` which may be used when creating
a repository. The repository defaults to using
https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-iam-roles.html[ECS
IAM Role] or
https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html[EC2
IAM Role] credentials for authentication. The only mandatory setting is the
bucket name:

[source,console]
----
PUT _snapshot/my_s3_repository
{
  "type": "s3",
  "settings": {
    "bucket": "my_bucket"
  }
}
----
// TEST[skip:we don't have s3 setup while testing this]


[[repository-s3-client]]
==== Client Settings

The client that you use to connect to S3 has a number of settings available.
The settings have the form `s3.client.CLIENT_NAME.SETTING_NAME`. By default,
`s3` repositories use a client named `default`, but this can be modified using
the <<repository-s3-repository,repository setting>> `client`. For example:

[source,console]
----
PUT _snapshot/my_s3_repository
{
  "type": "s3",
  "settings": {
    "bucket": "my_bucket",
    "client": "my_alternate_client"
  }
}
----
// TEST[skip:we don't have S3 setup while testing this]

Most client settings can be added to the `elasticsearch.yml` configuration file
with the exception of the secure settings, which you add to the {es} keystore.
For more information about creating and updating the {es} keystore, see
{ref}/secure-settings.html[Secure settings].

For example, if you want to use specific credentials to access S3 then run the
following commands to add these credentials to the keystore:

[source,sh]
----
bin/elasticsearch-keystore add s3.client.default.access_key
bin/elasticsearch-keystore add s3.client.default.secret_key
# a session token is optional so the following command may not be needed
bin/elasticsearch-keystore add s3.client.default.session_token
----

If instead you want to use the instance role or container role to access S3
then you should leave these settings unset. You can switch from using specific
credentials back to the default of using the instance role or container role by
removing these settings from the keystore as follows:
<commit_msg>Update repository-s3.asciidoc<commit_after>[[repository-s3]]
=== S3 Repository Plugin

The S3 repository plugin adds support for using AWS S3 as a repository for
{ref}/modules-snapshots.html[Snapshot/Restore].

*If you are looking for a hosted solution of Elasticsearch on AWS, please visit
https://www.elastic.co/cloud/.*

:plugin_name: repository-s3
include::install_remove.asciidoc[]

[[repository-s3-usage]]
==== Getting Started

The plugin provides a repository type named `s3` which may be used when creating
a repository. The repository defaults to using
https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-iam-roles.html[ECS
IAM Role] or
https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html[EC2
IAM Role] credentials for authentication. The only mandatory setting is the
bucket name:

[source,console]
----
PUT _snapshot/my_s3_repository
{
  "type": "s3",
  "settings": {
    "bucket": "my_bucket"
  }
}
----
// TEST[skip:we don't have s3 setup while testing this]


[[repository-s3-client]]
==== Client Settings

The client that you use to connect to S3 has a number of settings available.
The settings have the form `s3.client.CLIENT_NAME.SETTING_NAME`. By default,
`s3` repositories use a client named `default`, but this can be modified using
the <<repository-s3-repository,repository setting>> `client`. For example:

[source,console]
----
PUT _snapshot/my_s3_repository
{
  "type": "s3",
  "settings": {
    "bucket": "my_bucket",
    "client": "my_alternate_client"
  }
}
----

*bucket:*  The name of the bucket to be used for snapshots. (Mandatory)
Note that the bucket name can be between 3 and 63 characters long, and can contain only lower-case characters, numbers, periods, and dashes it cannot contain underscores, end with a dash, have consecutive periods, or use dashes adjacent to periods

The bucket naming convention is outlines in AWS [here] (https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-s3-bucket-naming-requirements.html)



// TEST[skip:we don't have S3 setup while testing this]



Most client settings can be added to the `elasticsearch.yml` configuration file
with the exception of the secure settings, which you add to the {es} keystore.
For more information about creating and updating the {es} keystore, see
{ref}/secure-settings.html[Secure settings].

For example, if you want to use specific credentials to access S3 then run the
following commands to add these credentials to the keystore:

[source,sh]
----
bin/elasticsearch-keystore add s3.client.default.access_key
bin/elasticsearch-keystore add s3.client.default.secret_key
# a session token is optional so the following command may not be needed
bin/elasticsearch-keystore add s3.client.default.session_token
----

If instead you want to use the instance role or container role to access S3
then you should leave these settings unset. You can switch from using specific
credentials back to the default of using the instance role or container role by
removing these settings from the keystore as follows:

{'fraction_non_alphanumeric': 0.0940110183046028, 'fraction_numerical': 0.010129731650968544, 'mean_word_length': 4.594433399602385, 'pattern_counts': {'":': 14, '<': 7, '<?xml version=': 0, '>': 7, 'https://': 7, 'lorem ipsum': 0, 'www.': 2, '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': '2996987', 'n_tokens_mistral': 1652, 'n_tokens_neox': 1625, 'n_words': 650}