elasticsearch/docs/reference/snapshot-restore/repository-read-only-url.asciidoc

[[snapshots-read-only-repository]]
=== Read-only URL repository

include::{es-repo-dir}/snapshot-restore/on-prem-repo-type.asciidoc[]

You can use a URL repository to give a cluster read-only access to a shared file
system. Since URL repositories are always read-only, they're a safer and more
convenient alternative to registering a read-only shared filesystem repository.

Use {kib} or the <<put-snapshot-repo-api,create snapshot repository API>> to
register a URL 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]

[[read-only-url-repository-settings]]
==== Repository settings

`chunk_size`::
(Optional, <<byte-units,byte value>>)
Maximum size of files in snapshots. In snapshots, files larger than this are
broken down into chunks of this size or smaller. Defaults to `null` (unlimited
file size).

`http_max_retries`::
(Optional, integer) Maximum number of retries for `http` and `https` URLs.
Defaults to `5`.

`http_socket_timeout`::
(Optional, <<time-units,time value>>) Maximum wait time for data transfers over
a connection. Defaults to `50s`.

`compress`::
(Optional, Boolean)
If `true`, metadata files, such as index mappings and settings, are compressed
in snapshots. Data files are not compressed. Defaults to `true`.

`max_number_of_snapshots`::
(Optional, integer)
Maximum number of snapshots the repository can contain.
Defaults to `Integer.MAX_VALUE`, which is `2^31-1` or `2147483647`.

include::repository-shared-settings.asciidoc[tags=!readonly-repo-setting]

`url`::
+
--
(Required, string)
URL location of the root of the shared filesystem repository. The following
protocols are supported:

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

URLs using the `http`, `https`, or `ftp` protocols must be explicitly allowed
with the <<repositories-url-allowed,`repositories.url.allowed_urls`>> cluster
setting. This setting supports wildcards in the place of a host, path, query, or
fragment in the URL.

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. You don't need to register URLs using the
`ftp`, `http`, `https`, or `jar` protocols in the `path.repo` setting.
--