doc: Update section on NFS

The old section was ancient and didn't seem very helpful.  Here, we
add some concrete advice on particular mount options.

Reviewed-by: Joe Conway 
Discussion: https://www.postgresql.org/message-id/flat/e90f24bb-5423-6abb-58ec-501176eb4afc%402ndquadrant.com

diff --git a/doc/src/sgml/runtime.sgml b/doc/src/sgml/runtime.sgml
index 388dc7e9662b836e3c7c02ba246a4ad7f2134917..e784268512052773718a5ec45446c8207ac1ea4c 100644 (file)
--- a/doc/src/sgml/runtime.sgml
+++ b/doc/src/sgml/runtime.sgml
@@ -229,42 +229,75 @@ postgres$ initdb -D /usr/local/pgsql/data
 
   
 
-  
-   Use of Network File Systems
-
-   
-    Network File Systems
-   
-   NFSNetwork File Systems
-   Network Attached Storage (NAS)Network File Systems
+  
+   File Systems
 
    
-    Many installations create their database clusters on network file
-    systems.  Sometimes this is done via NFS, or by using a
-    Network Attached Storage (NAS) device that uses
-    NFS internally.  PostgreSQL does nothing
-    special for NFS file systems, meaning it assumes
-    NFS behaves exactly like locally-connected drives.
-    If the client or server NFS implementation does not
-    provide standard file system semantics, this can
-    cause reliability problems (see 
-    url="https://www.time-travellers.org/shane/papers/NFS_considered_harmful.html">).
-    Specifically, delayed (asynchronous) writes to the NFS
-    server can cause data corruption problems.  If possible, mount the
-    NFS file system synchronously (without caching) to avoid
-    this hazard.  Also, soft-mounting the NFS file system is
-    not recommended.
+    Generally, any file system with POSIX semantics can be used for
+    PostgreSQL.  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.
    
 
-   
-    Storage Area Networks (SAN) typically use communication
-    protocols other than NFS, 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.
-    PostgreSQL cannot be more reliable than
-    the file system it's using.
-   
+   
+    NFS
+
+    
+     NFS
+    
+
+    
+     It is possible to use an NFS file system for storing
+     the PostgreSQL data directory.
+     PostgreSQL does nothing special for
+     NFS file systems, meaning it assumes
+     NFS behaves exactly like locally-connected drives.
+     PostgreSQL does not use any functionality that
+     is known to have nonstandard behavior on NFS, such as
+     file locking.
+    
 
+    
+     The only firm requirement for using NFS with
+     PostgreSQL is that the file system is mounted
+     using the hard option.  With the
+     hard option, processes can hang
+     indefinitely if there are network problems, so this configuration will
+     require a careful monitoring setup.  The soft option
+     will interrupt system calls in case of network problems, but
+     PostgreSQL will not repeat system calls
+     interrupted in this way, so any such interruption will result in an I/O
+     error being reported.
+    
+
+    
+     It is not necessary to use the sync mount option.  The
+     behavior of the async option is sufficient, since
+     PostgreSQL issues fsync
+     calls at appropriate times to flush the write caches.  (This is analogous
+     to how it works on a local file system.)  However, it is strongly
+     recommended to use the sync export option on the NFS
+     server on systems where it exists (mainly Linux).
+     Otherwise, an fsync or equivalent on the NFS client is
+     not actually guaranteed to reach permanent storage on the server, which
+     could cause corruption similar to running with the parameter 
+     linkend="guc-fsync"/> off.  The defaults of these mount and export
+     options differ between vendors and versions, so it is recommended to
+     check and perhaps specify them explicitly in any case to avoid any
+     ambiguity.
+    
+
+    
+     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.
+    
+