elasticsearch/docs/reference/snapshot-restore/repository-shared-file-system.asciidoc

[[snapshots-filesystem-repository]]
=== Shared file system repository

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

Use a shared file system repository to store snapshots on a shared file system.

To register a shared file system repository, first mount the file system to the
same location on all master and data nodes. Then add the file system's path or
parent directory to the `path.repo` setting in `elasticsearch.yml` for each
master and data node. For running clusters, this requires a
<<restart-cluster-rolling,rolling restart>> of each node.

Supported `path.repo` values vary by platform:

include::{es-ref-dir}/tab-widgets/register-fs-repo-widget.asciidoc[]

[[filesystem-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).

`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`.

`location`::
(Required, string)
Location of the shared filesystem used to store and retrieve snapshots. This
location must be registered in the `path.repo` setting on all master and data
nodes in the cluster. 
Unlike `path.repo`, this setting supports only a single file path.

`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[]

==== Troubleshooting a shared file system repository

{es} interacts with a shared file system repository using the file system
abstraction in your operating system. This means that every {es} node must be
able to perform operations within the repository path such as creating,
opening, and renaming files, and creating and listing directories, and
operations performed by one node must be visible to other nodes as soon as they
complete.

Check for common misconfigurations using the <<verify-snapshot-repo-api>> API
and the <<repo-analysis-api>> API. When the repository is properly configured,
these APIs will complete successfully. If the verify repository or repository
analysis APIs report a problem then you will be able to reproduce this problem
outside {es} by performing similar operations on the file system directly.

If the verify repository or repository analysis APIs fail with an error
indicating insufficient permissions then adjust the configuration of the
repository within your operating system to give {es} an appropriate level of
access. To reproduce such problems directly, perform the same operations as
{es} in the same security context as the one in which {es} is running. For
example, on Linux, use a command such as `su` to switch to the user as which
{es} runs.

If the verify repository or repository analysis APIs fail with an error
indicating that operations on one node are not immediately visible on another
node then adjust the configuration of the repository within your operating
system to address this problem. If your repository cannot be configured with
strong enough visibility guarantees then it is not suitable for use as an {es}
snapshot repository.

The verify repository and repository analysis APIs will also fail if the
operating system returns any other kind of I/O error when accessing the
repository. If this happens, address the cause of the I/O error reported by the
operating system.

TIP: Many NFS implementations match accounts across nodes using their _numeric_
user IDs (UIDs) and group IDs (GIDs) rather than their names. It is possible
for {es} to run under an account with the same name (often `elasticsearch`) on
each node, but for these accounts to have different numeric user or group IDs.
If your shared file system uses NFS then ensure that every node is running with
the same numeric UID and GID, or else update your NFS configuration to account
for the variance in numeric IDs across nodes.

[[repository-fs-linearizable-registers]]
==== Linearizable register implementation

The linearizable register implementation for shared filesystem repositories is
based around file locking. To perform a compare-and-exchange operation on a
register, {es} first locks he underlying file and then writes the updated
contents under the same lock. This ensures that the file has not changed in the
meantime.