summaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
authorJeff Darcy <jdarcy@redhat.com>2014-10-21 13:29:07 -0400
committerVijay Bellur <vbellur@redhat.com>2014-11-15 09:58:49 -0800
commitdfd3624ff6362ac58f57f9dd25c426dbfe488661 (patch)
treefda0287f17dc5ccda655ca72b80571bbe4225553 /doc
parentfdef42e82d66011a3a92c9c96db4ada2fa8d4814 (diff)
doc: update rebalance doc, add SSL/TLS doc
Change-Id: I5d21aabaa6bfa6de40459c9a1969832a0a5d75e1 Signed-off-by: Jeff Darcy <jdarcy@redhat.com> Reviewed-on: http://review.gluster.org/8961 Tested-by: Gluster Build System <jenkins@build.gluster.com> Reviewed-by: Xavier Hernandez <xhernandez@datalab.es> Reviewed-by: Vijay Bellur <vbellur@redhat.com>
Diffstat (limited to 'doc')
-rw-r--r--doc/admin-guide/en-US/markdown/admin_managing_volumes.md6
-rw-r--r--doc/admin-guide/en-US/markdown/admin_ssl.md128
2 files changed, 134 insertions, 0 deletions
diff --git a/doc/admin-guide/en-US/markdown/admin_managing_volumes.md b/doc/admin-guide/en-US/markdown/admin_managing_volumes.md
index cbd786e9814..3ac571c9a7e 100644
--- a/doc/admin-guide/en-US/markdown/admin_managing_volumes.md
+++ b/doc/admin-guide/en-US/markdown/admin_managing_volumes.md
@@ -366,6 +366,12 @@ layout information so that the files can also go to newly added nodes.
When this command is issued, all the file stat information which is
already cached will get revalidated.
+As of GlusterFS 3.6, the assignment of files to bricks will take into account
+the sizes of the bricks. For example, a 20TB brick will be assigned twice as
+many files as a 10TB brick. In versions before 3.6, the two bricks were
+treated as equal regardless of size, and would have been assigned an equal
+share of files.
+
A fix-layout rebalance will only fix the layout changes and does not
migrate data. If you want to migrate the existing data,
use`# gluster volume rebalance start ` command to rebalance data among
diff --git a/doc/admin-guide/en-US/markdown/admin_ssl.md b/doc/admin-guide/en-US/markdown/admin_ssl.md
new file mode 100644
index 00000000000..4522bcedf88
--- /dev/null
+++ b/doc/admin-guide/en-US/markdown/admin_ssl.md
@@ -0,0 +1,128 @@
+# Setting up GlusterFS with SSL/TLS
+
+GlusterFS allows its communication to be secured using the [Transport Layer
+Security][tls] standard (which supersedes Secure Sockets Layer), using the
+[OpenSSL][ossl] library. Setting this up requires a basic working knowledge of
+some SSL/TLS concepts, which can only be briefly summarized here.
+
+ * "Authentication" is the process of one entity (e.g. a machine, process, or
+ person) proving its identity to a second entity.
+
+ * "Authorization" is the process of checking whether an entity has permission
+ to perform an action.
+
+ * TLS provides authentication and encryption. It does not provide
+ authorization, though GlusterFS can use TLS-authenticated identities to
+ authorize client connections to bricks/volumes.
+
+ * An entity X which must authenticate to a second entity Y does so by sharing
+ with Y a *certificate*, which contains information sufficient to prove X's
+ identity. X's proof of identity also requires possession of a *private key*
+ which matches its certificate, but this key is never seen by Y or anyone
+ else. Because the certificate is already public, anyone who has the key can
+ claim that identity.
+
+ * Each certificate contains the identity of its principal (owner) along with
+ the identity of a *certifying authority* or CA who can verify the integrity
+ of the certificate's contents. The principal and CA can be the same (a
+ "self-signed certificate"). If they are different, the CA must *sign* the
+ certificate by appending information derived from both the certificate
+ contents and the CA's own private key.
+
+ * Certificate-signing relationships can extend through multiple levels. For
+ example, a company X could sign another company Y's certificate, which could
+ then be used to sign a third certificate Z for a specific user or purpose.
+ Anyone who trusts X (and is willing to extend that trust through a
+ *certificate depth* of two or more) would therefore be able to authenticate
+ Y and Z as well.
+
+ * Any entity willing to accept other entities' authentication attempts must
+ have some sort of database seeded with the certificates that already accept.
+
+In GlusterFS's case, a client or server X uses the following files to contain
+TLS-related information:
+
+ * /etc/ssl/glusterfs.pem X's own certificate
+
+ * /etc/ssl/glusterfs.key X's private key
+
+ * /etc/ssl/glusterfs.ca concatenation of *others'* certificates
+
+GlusterFS always performs *mutual authentication*, though clients do not
+currently do anything with the authenticated server identity. Thus, if client X
+wants to communicate with server Y, then X's certificate (or that of a signer)
+must be in Y's CA file, and vice versa.
+
+For all uses of TLS in GlusterFS, if one side of a connection is configured to
+use TLS then the other side must use it as well. There is no automatic fallback
+to non-TLS communication, or allowance for concurrent TLS and non-TLS access to
+the same resource, because either would be insecure. Instead, any such "mixed
+mode" connections will be rejected by the TLS-using side, sacrificing
+availability to maintain security.
+
+## Enabling TLS on the I/O Path
+
+To enable authentication and encryption between clients and brick servers, two
+options must be set:
+
+ gluster volume set MYVOLUME client.ssl on
+ gluster volume set MYVOLUME server.ssl on
+
+Note that the above options affect only the GlusterFS native protocol. Foreign
+protocols such as NFS, SMB, or Swift will not be affected.
+
+## Using TLS Identities for Authorization
+
+Once TLS has been enabled on the I/O path, TLS identities can be used instead of
+IP addresses or plain usernames to control access to specific volumes. For
+example:
+
+ gluster volume set MYVOLUME auth.ssl-allow Zaphod
+
+Here, we're allowing the TLS-authenticated identity "Zaphod" to access MYVOLUME.
+This is intentionally identical to the existing "auth.allow" option, except that
+the name is taken from a TLS certificate instead of a command-line string. Note
+that infelicities in the gluster CLI preclude using names that include spaces,
+which would otherwise be allowed.
+
+## Enabling TLS on the Management Path
+
+Management-daemon traffic is not controlled by an option. Instead, it is
+controlled by the presence of a file on each machine:
+
+ /var/lib/glusterd/secure-access
+
+Creating this file will cause glusterd connections made from that machine to use
+TLS. Note that even clients must do this to communicate with a remote glusterd
+while mounting, but not thereafter.
+
+## Additional Options
+
+The GlusterFS TLS implementation supports two additional options related to TLS
+internals.
+
+The first option allows the user to set the certificate depth, as mentioned
+above.
+
+ gluster volume set MYVOLUME ssl.cert-depth 2
+
+Here, we're setting our certificate depth to two, as in the introductory
+example. By default this value is zero, meaning that only certificates which
+are directly specified in the local CA file will be accepted (i.e. no signed
+certificates at all).
+
+The second option allows the user to specify the set of allowed TLS ciphers.
+
+ gluster volume set MYVOLUME ssl.cipher-list HIGH:!SSLv2
+
+Cipher lists are negotiated between the two parties to a TLS connection, so
+that both sides' security needs are satisfied. In this example, we're setting
+the initial cipher list to HIGH, representing ciphers that the cryptography
+community still believes to be unbroken. We are also explicitly disallowing
+ciphers specific to SSL version 2. The default is based on this example but
+also excludes CBC-based cipher modes to provide extra mitigation against the
+[POODLE][poo] attack.
+
+[tls]: http://tools.ietf.org/html/rfc5246
+[ossl]: https://www.openssl.org/
+[poo]: http://web.nvd.nist.gov/view/vuln/detail?vulnId=CVE-2014-3566