doc: Move relevant files out of legacy.

Change-Id: Iff9166dd7baa3d60b70ffab5ce9a692d211fa4fb
BUG: 811311
Signed-off-by: Vijay Bellur <vbellur@redhat.com>
Reviewed-on: http://review.gluster.org/5091
Reviewed-by: Justin Clift <jclift@redhat.com>
Tested-by: Gluster Build System <jenkins@build.gluster.com>

1 files changed, 112 insertions, 0 deletions

diff --git a/doc/authentication.txt b/doc/authentication.txt
new file mode 100644
index 00000000000..73cb21d73ba
--- /dev/null
+++ b/doc/authentication.txt
@@ -0,0 +1,112 @@
+
+* Authentication is provided by two modules addr and login. Login based authentication uses username/password from client for authentication. Each module returns either ACCEPT, REJCET or DONT_CARE. DONT_CARE is returned if the input authentication information to the module is not concerned to its working. The theory behind authentication is that "none of the auth modules should return REJECT and atleast one of them should return ACCEPT"
+
+* Currently all the authentication related information is passed un-encrypted over the network from client to server.
+
+----------------------------------------------------------------------------------------------------
+* options provided in protocol/client:
+	* for username/password based authentication:
+	      option username <username>
+	      option password <password>
+	* client can have only one set of username/password
+	* for addr based authentication:
+	      * no options required in protocol/client. Client has to bind to privileged port (port < 1024 ) which means the process in which protocol/client is loaded has to be run as root.
+
+----------------------------------------------------------------------------------------------------
+* options provided in protocol/server:
+	* for username/password based authentication:
+	      option auth.login.<brick>.allow [comma seperated list of usernames using which clients can connect to volume <brick>]
+	      option auth.login.<username>.password <password> #specify password <password> for username <username>
+	* for addr based authentication:
+	      option auth.addr.<brick>.allow [comma seperated list of ip-addresses/unix-paths from which clients are allowed to connect to volume <brick>]
+	      option auth.addr.<brick>.reject [comma seperated list of ip-addresses/unix-paths from which clients are not allowed to connect to volume <brick>]
+	* negation operator '!' is used to invert the sense of matching.
+	  Eg., option auth.addr.brick.allow !a.b.c.d #do not allow client from a.b.c.d to connect to volume brick
+	       option auth.addr.brick.reject !w.x.y.z #allow client from w.x.y.z to connect to volume brick
+	* wildcard '*' can be used to match any ip-address/unix-path
+
+----------------------------------------------------------------------------------------------------
+
+* Usecases:
+
+* username/password based authentication only
+      protocol/client:
+	option username foo
+	option password foo-password
+	option remote-subvolume foo-brick
+
+      protocol/server:
+	option auth.login.foo-brick.allow foo,who #,other users allowed to connect to foo-brick
+	option auth.login.foo.password foo-password
+	option auth.login.who.password who-password
+
+      * in protocol/server, dont specify ip from which client is connecting in auth.addr.foo-brick.reject list
+
+****************************************************************************************************
+
+* ip based authentication only
+      protocol/client:
+	option remote-subvolume foo-brick
+	* Client is connecting from a.b.c.d
+
+      protocol/server:
+	option auth.addr.foo-brick.allow a.b.c.d,e.f.g.h,i.j.k.l #, other ip addresses from which clients are allowed to connect to foo-brick
+
+****************************************************************************************************
+* ip and username/password based authentication
+  * allow only "user foo from a.b.c.d"
+    protocol/client:
+	option username foo
+	option password foo-password
+	option remote-subvolume foo-brick
+
+    protocol/server:
+	option auth.login.foo-brick.allow foo
+	option auth.login.foo.password foo-password
+	option auth.addr.foo-brick.reject !a.b.c.d
+
+  * allow only "user foo" from a.b.c.d i.e., only user foo is allowed from a.b.c.d, but anyone is allowed from ip addresses other than a.b.c.d
+    protocol/client:
+	option username foo
+	option password foo-password
+	option remote-subvolume foo-brick
+
+    protocol/server:
+	option auth.login.foo-brick.allow foo
+	option auth.login.foo.password foo-password
+	option auth.addr.foo-brick.allow !a.b.c.d
+
+  * reject only "user shoo from a.b.c.d"
+    protcol/client:
+	option remote-subvolume shoo-brick
+
+    protocol/server:
+	# observe that no "option auth.login.shoo-brick.allow shoo" given
+	# Also other users from a.b.c.d have to be explicitly allowed using auth.login.shoo-brick.allow ...
+	option auth.addr.shoo-brick.allow !a.b.c.d
+
+  * reject only "user shoo" from a.b.c.d i.e., user shoo from a.b.c.d has to be rejected.
+    * same as reject only "user shoo from a.b.c.d" above, but rules have to be added whether to allow ip addresses (and users from those ips) other than a.b.c.d
+
+****************************************************************************************************
+
+* ip or username/password based authentication
+
+  * allow user foo or clients from a.b.c.d
+    protocol/client:
+	option remote-subvolume foo-brick
+
+    protocol/server:
+	option auth.login.foo-brick.allow foo
+	option auth.login.foo.password foo-password
+	option auth.addr.foo-brick.allow a.b.c.d
+
+  * reject user shoo or clients from a.b.c.d
+    protocol/client:
+	option remote-subvolume shoo-brick
+
+    protocol/server:
+	option auth.login.shoo-brick.allow <usernames other than shoo>
+	#for each username mentioned in the above <usernames other than shoo> list, specify password as below
+	option auth.login.<username other than shoo>.password password
+	option auth.addr.shoo-brick.reject a.b.c.d