Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[7.8] [DOCS] Fix clarity of URL snapshot repo docs (#56920) #57213

Merged
merged 1 commit into from
May 27, 2020
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
55 changes: 43 additions & 12 deletions docs/reference/snapshot-restore/register-repository.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -163,24 +163,55 @@ unit, for example: `1GB`, `10MB`, `5KB`, `500B`. Defaults to `null` (unlimited c
[[snapshots-read-only-repository]]
=== Read-only URL repository

The URL repository (`"type": "url"`) can be used as an alternative read-only way to access data created by the shared file
system repository. The URL specified in the `url` parameter should point to the root of the shared filesystem repository.
The following settings are supported:
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.

[horizontal]
`url`:: Location of the snapshots. Mandatory.
To reduce this risk, you can use URL repositories (`"type": "url"`) to give one
or more clusters read-only access to a shared file system repository. As URL
repositories are always read-only, they are a safer and more convenient
alternative to registering a read-only shared filesystem repository.

The URL specified in the `url` parameter should point to the root of the shared
filesystem repository.

[source,console]
----
PUT /_snapshot/my_read_only_url_repository
{
"type": "url",
"settings": {
"url": "file:/mount/backups/my_fs_backup_location"
}
}
----
// TEST[skip:no access to url file path]

The `url` parameter supports the following protocols:

* `file`
* `ftp`
* `http`
* `https`
* `jar`

URL Repository supports the following protocols: "http", "https", "ftp", "file" and "jar". URL repositories with `http:`,
`https:`, and `ftp:` URLs has to be whitelisted by specifying allowed URLs in the `repositories.url.allowed_urls` setting.
This setting supports wildcards in the place of host, path, query, and fragment. For example:
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, similar to a
<<snapshots-filesystem-repository,shared file system repository>>.

URLs using the `ftp`, `http`, or `https` protocols must be whitelisted in the
`repositories.url.allowed_urls` setting. This setting supports wildcards (`*`)
in place of a host, path, query, or fragment in the URL. For example:

[source,yaml]
-----------------------------------
----
repositories.url.allowed_urls: ["http://www.example.org/root/*", "https://*.mydomain.com/*?*#*"]
-----------------------------------
----

URL repositories with `file:` URLs can only point to locations registered in the `path.repo` setting similar to
shared file system repository.
NOTE: URLs using the `ftp`, `http`, `https`, or `jar` protocols do not need to
be registered in the `path.repo` setting.

[float]
[role="xpack"]
Expand Down