Various doc fixes and improvements

Author: maxidorius

build.gradle

@@ -190,13 +190,13 @@ task debBuild(dependsOn: shadowJar) {
         ant.replaceregexp( // FIXME adapt to new config format
                 file: "${debBuildConfPath}/${debConfFileName}",
                 match: "key:\\R  path:(.*)",
-                replace: "key:\n  path: '${debDataPath}/signing.key'"
+                replace: "key:\n  path: '${debDataPath}/keys'"
         )
 
         ant.replaceregexp( // FIXME adapt to new config format
                 file: "${debBuildConfPath}/${debConfFileName}",
                 match: "storage:\\R  provider:\\R    sqlite:\\R      database:(.*)",
-                replace: "storage:\n  provider:\n    sqlite:\n      database: '${debDataPath}/mxisd.db'"
+                replace: "storage:\n  provider:\n    sqlite:\n      database: '${debDataPath}/store.db'"
         )
 
         copy {

docs/features/experimental/application-service.md

@@ -26,7 +26,7 @@ synapseSql:
   connection: '<DB CONNECTION URL>'
 ```
 
-The `synapseSql` section is used to retrieve display names which are not directly accessible in this mode.
+The `synapseSql` section is optional. It is used to retrieve display names which are not directly accessible in this mode.
 For details about `type` and `connection`, see the [relevant documentation](../../stores/synapse.md).
 If you do not configure it, some placeholders will not be available in the notification, like the Room name.
 

docs/features/federation.md

@@ -46,15 +46,6 @@ lookup:
 invite:
   resolution:
     recursive: false
-session:
-  policy:
-    validation:
-      forLocal:
-        toRemote:
-          enabled: false
-      forRemote:
-        toRemote:
-          enabled: false
 ``` 
 
 There is currently no way to selectively disable federation towards specific servers, but this feature is planned.

docs/features/identity.md

@@ -1,6 +1,4 @@
 # Identity
-**WARNING**: This document is incomplete and can be misleading.
-
 Implementation of the [Identity Service API r0.1.0](https://matrix.org/docs/spec/identity_service/r0.1.0.html).
 
 ## Lookups

docs/stores/exec.md

@@ -229,8 +229,12 @@ exec:
     output:
       type: 'json'
     exit:
-      success: [0, 128]
-      failure: [1, 129]
+      success:
+        - 0
+        - 128
+      failure:
+        - 1
+        - 129
 ```
 With:
 - The Identity store enabled for all features

docs/threepids/medium/email/smtp-connector.md

@@ -1,6 +1,4 @@
 # Email notifications - SMTP connector
-Enabled by default.
-
 Connector ID: `smtp`
 
 ## Configuration

docs/threepids/medium/msisdn/twilio-connector.md

@@ -1,6 +1,4 @@
 # SMS notifications - Twilio connector
-Enabled by default.
-
 Connector ID: `twilio`
 
 ## Configuration

docs/threepids/notification/template-generator.md

@@ -51,25 +51,13 @@ This template is used when someone is invited into a room using an email address
 | `%ROOM_NAME%`         | The Name of the room in which the invite took place. If not available/set, empty         |
 | `%ROOM_NAME_OR_ID%`   | The Name of the room in which the invite took place. If not available/set, its Matrix ID |
 
-### Local validation of 3PID Session
+### Validation of 3PID Session
 This template is used when to user which added their 3PID address to their profile/settings and the session policy
 allows at least local sessions.  
 
 #### Placeholders
 | Placeholder          | Purpose                                                                              |
 |----------------------|--------------------------------------------------------------------------------------|
 | `%VALIDATION_LINK%`  | URL, including token, to validate the 3PID session.                                  |
-| `%VALIDATION_TOKEN%` | The token needed to validate the local session, in case the user cannot use the link |
-
-### Remote validation of 3PID Session
-This template is used when to user which added their 3PID address to their profile/settings and the session policy only
-allows remote sessions.
-
-**NOTE:** 3PID session always require local validation of a token, even if a remote session is enforced.  
-One cannot bind a Matrix ID to the session until both local and remote sessions have been validated.
-
-#### Placeholders
-| Placeholder          | Purpose                                                |
-|----------------------|--------------------------------------------------------|
-| `%VALIDATION_TOKEN%` | The token needed to validate the session               |
-| `%NEXT_URL%`         | URL to continue with remote validation of the session. |
+| `%VALIDATION_TOKEN%` | The token needed to validate the session, in case the user cannot use the link.      |
+| `%NEXT_URL%`         | URL to redirect to after the sessions has been validated.                            |

mxisd.example.yaml

@@ -1,6 +1,11 @@
 # Sample configuration file explaining the minimum required keys to be set to run mxisd
 #
 # For a complete list of options, see https://github.com/kamax-matrix/mxisd/docs/README.md
+#
+# Please follow the Getting Started guide if this is your first time using/configuring mxisd
+#
+#  -- https://github.com/kamax-matrix/mxisd/blob/master/docs/getting-started.md#getting-started
+#
 
 #######################
 # Matrix config items #
@@ -16,75 +21,59 @@ matrix:
 ################
 # Signing keys #
 ################
-# Absolute path for the Identity Server signing key.
-# This is **NOT** your homeserver key.
-# The signing key is auto-generated during execution time if not present.
+# Absolute path for the Identity Server signing keys database.
+# /!\ THIS MUST **NOT** BE YOUR HOMESERVER KEYS FILE /!\
+# If this path does not exist, it will be auto-generated.
 #
-# During testing, /var/tmp/mxisd.key is a possible value
+# During testing, /var/tmp/mxisd/keys is a possible value
 # For production, recommended location shall be one of the following:
-#   - /var/opt/mxisd/sign.key
-#   - /var/local/mxisd/sign.key
-#   - /var/lib/mxisd/sign.key
+#   - /var/lib/mxisd/keys
+#   - /var/opt/mxisd/keys
+#   - /var/local/mxisd/keys
 #
 key:
   path: ''
 
 
 # Path to the SQLite DB file for mxisd internal storage
+# /!\ THIS MUST **NOT** BE YOUR HOMESERVER DATABASE /!\
 #
 # Examples:
-#  - /var/opt/mxisd/mxisd.db
-#  - /var/local/mxisd/mxisd.db
-#  - /var/lib/mxisd/mxisd.db
+#  - /var/opt/mxisd/store.db
+#  - /var/local/mxisd/store.db
+#  - /var/lib/mxisd/store.db
 #
 storage:
   provider:
     sqlite:
       database: '/path/to/mxisd.db'
 
 
-####################
-# Fallback servers #
-####################
-#
-# Root/Central servers to be used as final fallback when performing lookups.
-# By default, for privacy reasons, matrix.org servers are not enabled.
-# See the following issue: https://github.com/kamax-matrix/mxisd/issues/76
-#
-# If you would like to use them and trade away your privacy for convenience, uncomment the following option:
+###################
+# Identity Stores #
+###################
+# If you are using synapse standalone and do not have an Identity store,
+# see https://github.com/kamax-matrix/mxisd/blob/master/docs/stores/synapse.md#synapse-identity-store
 #
-#forward:
-#  servers: ['matrix-org']
-
-
-################
-# LDAP Backend #
-################
 # If you would like to integrate with your AD/Samba/LDAP server,
 # see https://github.com/kamax-matrix/mxisd/blob/master/docs/stores/ldap.md
-
-
-###############
-# SQL Backend #
-###############
-# If you would like to integrate with a MySQL/MariaDB/PostgreQL/SQLite DB,
-# see https://github.com/kamax-matrix/mxisd/blob/master/docs/stores/sql.md
-
-
-################
-# REST Backend #
-################
-# If you would like to integrate with an existing web service/webapp,
-# see https://github.com/kamax-matrix/mxisd/blob/master/docs/stores/rest.md
+#
+# For any other Identity store, or to simply discover them,
+# see https://github.com/kamax-matrix/mxisd/blob/master/docs/stores/README.md
 
 
 #################################################
 # Notifications for invites/addition to profile #
 #################################################
-# If you would like to change the content,
+# This is mandatory to deal with anything e-mail related.
+#
+# For an introduction to sessions, invites and 3PIDs in general,
+# see https://github.com/kamax-matrix/mxisd/blob/master/docs/threepids/session/session.md#3pid-sessions
+#
+# If you would like to change the content of the notifications,
 # see https://github.com/kamax-matrix/mxisd/blob/master/docs/threepids/notification/template-generator.md
 #
-#### E-mail invite sender
+#### E-mail connector
 threepid:
   medium:
     email:
@@ -100,12 +89,13 @@ threepid:
           # SMTP port
           port: 587
 
-          # TLS mode for the connection.
+          # STARTLS mode for the connection.
+          # SSL/TLS is currently not supported. See https://github.com/kamax-matrix/mxisd/issues/125
           #
           # Possible values:
-          #  0    Disable TLS entirely
-          #  1    Enable TLS if supported by server (default)
-          #  2    Force TLS and fail if not available
+          #  0    Disable any kind of TLS entirely
+          #  1    Enable STARTLS if supported by server (default)
+          #  2    Force STARTLS and fail if not available
           #
           tls: 1