From 0eb0cac0bf027f17439ada98b64fb923717bb14c Mon Sep 17 00:00:00 2001
From: Prashanth Pai <ppai@redhat.com>
Date: Fri, 17 Jun 2016 12:08:45 +0530
Subject: doc: Add troubleshooting section

* Mention glusterfs versions which requires additional steps to allow
  non-root users to mount the volume.
* Add note on tested platform and python versions.
* Remove TODOs and add them as issues on GitHub

Change-Id: I36a63ff2b9f98de82c2fd58542584565dab7dda0
Signed-off-by: Prashanth Pai <ppai@redhat.com>
---
 README.md               | 13 ++-----------
 doc/install.rst         | 34 ++++------------------------------
 doc/troubleshooting.rst | 48 ++++++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 54 insertions(+), 41 deletions(-)
 create mode 100644 doc/troubleshooting.rst

diff --git a/README.md b/README.md
index 1fa9fba..c7710b5 100644
--- a/README.md
+++ b/README.md
@@ -6,14 +6,5 @@ This is the official python bindings for the
 Complete API reference and documentation can be found at
 [ReadTheDocs](http://libgfapi-python.readthedocs.io/)
 
-### TODOs
-
-* Submit to pypy to enable installing using pip
-* Add support for py3
-* Implement async I/O APIs
-* Implement file locking APIs
-* Implement os.scandir() like API that leverages d\_type
-* Improve Volume.walk() by leveraging scandir.
-* Test and allow protocols other than TCP such as rdma and socket.
-
-Please follow the [Developer Guide](doc/markdown/dev_guide.md) to contribute code.
+Please follow the [Developer Guide](doc/markdown/dev_guide.md) to
+contribute code.
diff --git a/doc/install.rst b/doc/install.rst
index d256376..5d0ed84 100644
--- a/doc/install.rst
+++ b/doc/install.rst
@@ -1,7 +1,7 @@
 Installation
 ============
 
-Install glusterfs:
+Install glusterfs libgfapi C library:
 
 .. code-block:: console
 
@@ -15,32 +15,6 @@ Install libgfapi-python from source:
    $ cd libgfapi-python
    $ sudo python setup.py install
 
-Mount GlusterFS volume as non-root user
----------------------------------------
-
-One can follow the following steps to allow a non-root user to virtual mount
-a GlusterFS volume over libgfapi. This requires a configuration change which
-enables GlusterFS server to accept client connections from non-priveledged
-ports.
-
-.. code-block:: console
-
-    # gluster volume set <volname> server.allow-insecure on
-    # gluster volume stop <volname>
-    # gluster volume start <volname>
-
-Edit `/etc/glusterfs/glusterd.vol` or `/usr/local/etc/glusterfs/glusterd.vol`
-and set:
-
-.. code-block:: aconf
-
-    option rpc-auth-allow-insecure on
-
-Restart glusterd service:
-
-.. code-block:: console
-
-    # service glusterd restart
-
-Further, use `chown` and/or `chmod` commands to change permissions on mount
-point or required directories to allow non-root access to appropriate users.
+.. note::
+    libgfapi-python bindings has been tested only against **Linux x86-64** and
+    Python versions **2.6** and **2.7**
diff --git a/doc/troubleshooting.rst b/doc/troubleshooting.rst
new file mode 100644
index 0000000..a183e95
--- /dev/null
+++ b/doc/troubleshooting.rst
@@ -0,0 +1,48 @@
+Troubleshooting
+===============
+
+Mount GlusterFS volume as non-root user
+---------------------------------------
+
+.. versionchanged:: 3.7.3
+    GlusterFS versions prior to version **3.7.3** requires the following
+    additional steps to allow non-root users to mount the volume over libgfapi.
+    Following these steps is not required for recent versions i.e >= 3.7.3
+
+One can follow the following steps to allow a non-root user to virtual mount
+a GlusterFS volume over libgfapi. This requires a configuration change which
+enables GlusterFS server to accept client connections from non-priveledged
+ports.
+
+.. code-block:: console
+
+    # gluster volume set <volname> server.allow-insecure on
+    # gluster volume stop <volname>
+    # gluster volume start <volname>
+
+Edit `/etc/glusterfs/glusterd.vol` or `/usr/local/etc/glusterfs/glusterd.vol`
+and set:
+
+.. code-block:: aconf
+
+    option rpc-auth-allow-insecure on
+
+Restart glusterd service:
+
+.. code-block:: console
+
+    # service glusterd restart
+
+Further, use `chown` and/or `chmod` commands to change permissions on mount
+point or required directories to allow non-root access to appropriate users.
+
+If you do not provide a custom location for log file, you might see an error
+similar to the following during mount.
+
+.. code-block:: python
+
+   LibgfapiException: glfs_set_logging(None, 7) failed: Permission denied
+
+In such case, provide a log file path that has appropriate write permissions
+or change permission of default log location i.e `/var/log/glusterfs` or
+`/usr/local/var/log/glusterfs` accordingly.
-- 
cgit