0001-doc-Update-section-on-NFS.patch

From 6b9430b395997955be718244d0061eceb1319a9e Mon Sep 17 00:00:00 2001
From: Peter Eisentraut <peter@eisentraut.org>
Date: Tue, 23 Apr 2019 12:03:57 +0200
Subject: [PATCH] doc: Update section on NFS

---
 doc/src/sgml/runtime.sgml | 71 ++++++++++++++++++++++-----------------
 1 file changed, 40 insertions(+), 31 deletions(-)

diff --git a/doc/src/sgml/runtime.sgml b/doc/src/sgml/runtime.sgml
index 388dc7e966..7c76f5b8aa 100644
--- a/doc/src/sgml/runtime.sgml
+++ b/doc/src/sgml/runtime.sgml
@@ -229,42 +229,51 @@ <title>Use of Secondary File Systems</title>
 
   </sect2>
 
-  <sect2 id="creating-cluster-nfs">
-   <title>Use of Network File Systems</title>
-
-   <indexterm zone="creating-cluster-nfs">
-    <primary>Network File Systems</primary>
-   </indexterm>
-   <indexterm><primary><acronym>NFS</acronym></primary><see>Network File Systems</see></indexterm>
-   <indexterm><primary>Network Attached Storage (<acronym>NAS</acronym>)</primary><see>Network File Systems</see></indexterm>
+  <sect2 id="creating-cluster-filesystem">
+   <title>File Systems</title>
 
    <para>
-    Many installations create their database clusters on network file
-    systems.  Sometimes this is done via <acronym>NFS</acronym>, or by using a
-    Network Attached Storage (<acronym>NAS</acronym>) device that uses
-    <acronym>NFS</acronym> internally.  <productname>PostgreSQL</productname> does nothing
-    special for <acronym>NFS</acronym> file systems, meaning it assumes
-    <acronym>NFS</acronym> behaves exactly like locally-connected drives.
-    If the client or server <acronym>NFS</acronym> implementation does not
-    provide standard file system semantics, this can
-    cause reliability problems (see <ulink
-    url="https://www.time-travellers.org/shane/papers/NFS_considered_harmful.html"></ulink>).
-    Specifically, delayed (asynchronous) writes to the <acronym>NFS</acronym>
-    server can cause data corruption problems.  If possible, mount the
-    <acronym>NFS</acronym> file system synchronously (without caching) to avoid
-    this hazard.  Also, soft-mounting the <acronym>NFS</acronym> file system is
-    not recommended.
+    Generally, any file system with POSIX semantics can be used for
+    PostgreSQL.  (On Windows, all standard Windows file systems are
+    supported. XXX?)  Users prefer different file systems for a variety of
+    reasons, including vendor support, performance, and familiarity.
+    Experience suggests that, all other things being equal, one should not
+    expect major performance or behavior changes merely from switching file
+    systems or making minor file system configuration changes.
    </para>
 
-   <para>
-    Storage Area Networks (<acronym>SAN</acronym>) typically use communication
-    protocols other than <acronym>NFS</acronym>, and may or may not be subject
-    to hazards of this sort.  It's advisable to consult the vendor's
-    documentation concerning data consistency guarantees.
-    <productname>PostgreSQL</productname> cannot be more reliable than
-    the file system it's using.
-   </para>
+   <sect3 id="creating-cluster-nfs">
+    <title>NFS</title>
+
+    <indexterm zone="creating-cluster-nfs">
+     <primary>NFS</primary>
+    </indexterm>
 
+    <para>
+     It is possible to use an NFS file system for storing the
+     <productname>PostgreSQL</productname> data directory.  The only
+     requirement is that the file system is mounted using the
+     <literal>hard</literal> option.  With the <literal>hard</literal> option,
+     processes can <quote>hang</quote> indefinitely if there are network
+     problems, so this setup will require a careful monitoring setup.  (The
+     <literal>soft</literal> option will interrupt system calls in case of
+     network problems, but the <productname>PostgreSQL</productname> will not
+     repeat system calls interrupted in this way, so any such interruption
+     will result in an I/O error being reported.)
+     <productname>PostgreSQL</productname> does nothing special for
+     <acronym>NFS</acronym> file systems, meaning it assumes
+     <acronym>NFS</acronym> behaves exactly like locally-connected drives.
+    </para>
+
+    <para>
+     In some cases, an external storage product can be accessed either via NFS
+     or a lower-level protocol such as iSCSI.  In the latter case, the storage
+     appears as a block device and any available file system can be created on
+     it.  That approach might relieve the DBA from having to deal with some of
+     the idiosyncrasies of NFS, but of course the complexity of managing
+     remote storage then happens at other levels.
+    </para>
+   </sect3>
   </sect2>
 
  </sect1>
-- 
2.21.0