From 2bc05286560a028096af6020866035ebbf0cedd4 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Marcin=20=C5=81ojewski?= <marcin.lojewski@mlojewski.me>
Date: Tue, 12 Jun 2018 23:45:53 +0200
Subject: [PATCH] New readme pt. 1

---
 README.md | 63 +++++++++++++++++++++++++++++++++++++++++++++++--------
 1 file changed, 54 insertions(+), 9 deletions(-)

diff --git a/README.md b/README.md
index 1ec67ec..9ba1649 100644
--- a/README.md
+++ b/README.md
@@ -5,21 +5,66 @@ user_sql
 
 ![](https://github.com/nextcloud/user_sql/blob/master/screenshot.png)
 
+Use external database as a source for Nextcloud users and groups.
+Retrieve the users and groups info. Allow the users to change their passwords.
+Sync the users' email addresses with the addresses stored by Nextcloud.
+
 ## Getting Started
-1. SSH into your server
 
-2. Get into the apps folder of your Nextcloud installation, for example /var/www/nextcloud/apps
+1. SSH into your server.
 
-3. Git clone this project
-```
-git clone https://github.com/nextcloud/user_sql.git
-```
+2. Get into the apps folder of your Nextcloud installation, for example */var/www/nextcloud/apps*.
 
-4. Login your Nextcloud as admin
+3. Git clone this project: `git clone https://github.com/nextcloud/user_sql.git`
 
-5. Navigate to Apps from the menu and enable the SQL user backend 
+4. Login to your Nextcloud instance as admin.
 
-6. Navigate to Admin from menu and switch to Additional Settings, scroll down the page and you will see SQL User Backend settings
+5. Navigate to Apps from the menu then find and enable the *User and Group SQL Backends* app.
+
+6. Navigate to Admin from menu and switch to Additional Settings, scroll down the page and you will see *SQL Backends* settings.
+
+*You can skip the first three steps as this app is available in the official Nextcloud App Store.*
+
+## Configuration
+
+Below are detailed descriptions of all available options. The options are mandatory if not said differently.
+
+### Database connection
+
+This section contains database connection parameters. 
+
+**SQL driver** - The database driver to use. Currently supported drivers are: mysql, pgsql.
+
+**Hostname** - The hostname on which the database server resides.
+ 
+**Database** - The name of the database.
+
+**Username** - The name of the user for the connection. (optional) 
+
+**Password** - The password of the user for the connection. (optional)
+
+#### Options
+
+**Allow display name change** - With this option enabled user can change its display name. The change is propagated to the database. (optional, default: 0)
+
+**Allow password change** - Can user change its password. The password hash is propagated to the database. See [Hash algorithms](#Hash algorithms). (optional, default: 0)
+ 
+**Use cache** - Use database query results cache. The cache can be cleared any time with the *Clear cache* button click. (optional, default: 0)
+
+**Hashing algorithm** - How users passwords are store in the database. See [Hash algorithms](#Hash algorithms).
+
+**Email sync** - Sync e-mail address with the Nextcloud.
+ - *None* - Disables this feature. This is the default option.
+ - *Synchronise only once* - Copy the e-mail address to the Nextcloud storage if its not set.
+ - *Nextcloud always wins* - Always copy the e-mail address to the database. This updates the user table.
+ - *SQL always wins* - Always copy the e-mail address to the Nextcloud storage.
+
+**Home mode** - User's storage path.
+ - *Default* - Let the Nextcloud manage this. The default option.
+ - *Query* - Use location from the database pointed by the home column.
+ - *Static* - Use static location. The `%u` variable by replaced with the username of the user.
+
+**Home Location** - User storage location for the static home mode. Mandatory if the *Home mode* is set to `Static`.
 
 ## Integrations