Skip to content

Commit

Permalink
[DOCS] Fix clarity of URL snapshot repo docs (#56920) (#57212)
Browse files Browse the repository at this point in the history
Makes following changes to better clarify docs for read-only URL
snapshot repositories:

* Adds an example snippet for registering a URL repository
* Rewrites the protocols paragraph
* Adds a note to explicitly point out that only URLs using the `ftp`,
  `http`, `http`, and `jar` protocols do not need the `path.repo`
  setting.

Fixes #16280
  • Loading branch information
jrodewig authored May 27, 2020
1 parent 0e34b2f commit 5ae650e
Showing 1 changed file with 43 additions and 12 deletions.
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

0 comments on commit 5ae650e

Please sign in to comment.