From 605f281b37db63ee238fb2aaf5c0563effce4619 Mon Sep 17 00:00:00 2001
From: Steve Groesz <wolfpackmars2@yahoo.com>
Date: Wed, 5 Apr 2017 20:29:04 -0500
Subject: [PATCH] Document repository file system requirements

#2080
---
 docs/installation.rst | 31 +++++++++++++++++++++++++++++++
 1 file changed, 31 insertions(+)

diff --git a/docs/installation.rst b/docs/installation.rst
index 26a200afc..ef5762c70 100644
--- a/docs/installation.rst
+++ b/docs/installation.rst
@@ -20,6 +20,37 @@ There are different ways to install |project_name|:
     have the latest code or use revision control (each release is
     tagged).
 
+.. _installation-requirements:
+
+Pre-Installation Considerations
+-------------------------------
+
+Repository File System
+~~~~~~~~~~~~~~~~~~~~~~
+:ref:data-structures-and-file-formats
+- |project_name| stores data only 3 directory levels deep and uses short file and
+  directory names.
+- |project_name| requires read and write permissions on the repository file system.
+- |project_name| stores backup metadata and data into so-called segment files. The 
+  target size of these files and also the count of these files per directory is set 
+  in the :ref:config-file.
+- |project_name| uses a generic and very portable mkdir-based `locking<https://en.wikipedia.org/wiki/File_locking#Lock_files`_ mechanism.
+  POSIX locks, NFS locks, windows file locks, lockf(), flock() and hardlinks are
+  **not** used.
+- Hardlinks are only required when performing an in-place upgrade of an Attic
+  repository. 
+- A journaling file system is strongly recommended. More information can be
+  found in :ref:`file-systems`.
+- |project_name| requires the following file system operations:
+  - create, open, read, write, seek, close, rename, delete
+  - link - when upgrading an Attic repo in-place
+  - listdir, stat
+  - posix_fadvise - to not flood the operating system's cache
+  - sync on files and directories to ensure data is written onto storage media
+
+:ref:data-structures-and-file-formats contains additional information about how |project_name|
+manages data.
+
 .. _distribution-package:
 
 Distribution Package