From: Ralph Boehme Date: Sun, 11 Feb 2018 08:12:16 +0000 (+0100) Subject: docs-xml: add "persistent handles" and "continuous availability" options X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=caf00fa83c64e33b02c6213f00b0ccd8d34d5b59;p=thirdparty%2Fsamba.git docs-xml: add "persistent handles" and "continuous availability" options Signed-off-by: Ralph Boehme Reviewed-by: Anoop C S --- diff --git a/docs-xml/smbdotconf/protocol/continuousavailability.xml b/docs-xml/smbdotconf/protocol/continuousavailability.xml new file mode 100644 index 00000000000..75917ba1178 --- /dev/null +++ b/docs-xml/smbdotconf/protocol/continuousavailability.xml @@ -0,0 +1,20 @@ + + + + This boolean parameter controls whether a share is Continuously Available + and enables Transparent Failover. + + + Check the description for for + further details describing this option and how to use it. + + + Warning: Note that this feature is still considered experimental. + + + +no + diff --git a/docs-xml/smbdotconf/protocol/persistenthandles.xml b/docs-xml/smbdotconf/protocol/persistenthandles.xml new file mode 100644 index 00000000000..777c7e51aac --- /dev/null +++ b/docs-xml/smbdotconf/protocol/persistenthandles.xml @@ -0,0 +1,92 @@ + + + + This boolean parameter controls whether Samba supports Persistent Handles. + + + + The option enables Samba's + support for SMB3 Persistent Handles, a mechanism that allows SMB clients + to retain valid file handles across server restarts or outages. When + enabled, Samba stores all relevant filehandle state in a durable, on-disk + database so that the handle can be reconstructed when the client + reconnects. + + + Note that persistent handles are only enabled if + no, + no, and + no, + i.e. if the share is configured for CIFS/SMB2 only access, + not supporting interoperability features with local UNIX processes + or NFS operations. + + + Persistent Handles are a fundamental building block for Continuous + Availability (CA) workloads where an application expects I/O operations to + remain valid even in the presence of server-side failures. + + + This option controls whether Samba announces the global server capability + SMB2_CAP_PERSISTENT_HANDLES and Persistent Handles + are internally active. For clients to actually use Persistent Handles on a + given share, the per-share option must also be set. + + + Typical use cases include: + + + + Host and access VM disks over SMB3 + + + Database or clustered application storage + + + + Enabling this feature has significant performance implications: + + + + All filehandle state must be persisted on disk, not just stored in + volatile memory or clustered databases. This results in increased + synchronous I/O for every handle creation, update, and close + event. + + + Much higher latency for open, lease, and handle update operations, + especially under heavy load. + + + + Environments that do not require Continuous Availability benefit from + leaving this option disabled. + + + Recommended Configuration: + + + + Enable only if your + deployment requires SMB3 Continuous Availability semantics. + + + Then enable on + specific shares that should support Persistent Handles. + + + Leave the option disabled in general-purpose file server workloads + where performance is preferred over CA semantics. + + + + Warning: Note that this feature is still considered experimental. + + + +no +