updated documentation and changelog

added some documentation for cli commands config-dump and config-update

CHANGELOG.md

@@ -28,6 +28,7 @@ deprecated before 1.8.0, you can switch to an external database server by then.
 - Features: use HTTP/1.1 for proxyied connections ([#1070](https://github.com/Mailu/Mailu/issues/1070))
 - Features: Update Rainloop to 1.13.0 ([#1071](https://github.com/Mailu/Mailu/issues/1071))
 - Features: Use python package socrate instead of Mailustart ([#1082](https://github.com/Mailu/Mailu/issues/1082))
+- Features: Added cli command config-dump ([#1377](https://github.com/Mailu/Mailu/issues/1377))
 - Bugfixes: Use ldez/traefik-certs-dumper in our certificate dumper to have a more robust solution ([#820](https://github.com/Mailu/Mailu/issues/820))
 - Bugfixes: Make aliases optionally case-insensitive: After attempting to resolve an alias in its preserved case, also attempt to match it case-insensitively ([#867](https://github.com/Mailu/Mailu/issues/867))
 - Bugfixes: Fix HOST_* variable usage ([#884](https://github.com/Mailu/Mailu/issues/884))
@@ -47,6 +48,7 @@ deprecated before 1.8.0, you can switch to an external database server by then.
 - Enhancement: Create an Authentication Token with IPv6 address restriction ([#829](https://github.com/Mailu/Mailu/issues/829))
 - Enhancement: Automatically create admin user on container startup if given appropriate environment variables
 - Enhancement: Missing wildcard option in alias flask command ([#869](https://github.com/Mailu/Mailu/issues/869))
+- Enhancement: Cli command config-update now updates all objects and parameters ([#1377](https://github.com/Mailu/Mailu/issues/1377))
 
 v1.6.0 - 2019-01-18
 -------------------

docs/cli.rst

@@ -10,6 +10,7 @@ Managing users and aliases can be done from CLI using commands:
 * user
 * user-import
 * user-delete
+* config-dump
 * config-update
 
 alias
@@ -62,60 +63,124 @@ primary difference with simple `user` command is that password is being imported
   docker-compose run --rm admin flask mailu user-import myuser example.net '$6$51ebe0cb9f1dab48effa2a0ad8660cb489b445936b9ffd812a0b8f46bca66dd549fea530ce' 'SHA512-CRYPT'
 
 user-delete
-------------
+-----------
 
 .. code-block:: bash
 
   docker-compose exec admin flask mailu user-delete foo@example.net
 
+config-dump
+-----------
+
+The purpose of this command is to dump domain-, relay-, alias- and user-configuration to a YAML template.
+If you want to export non-hashed secrets you have to add the ``--secrets`` option.
+Only non-default options are dumped. If you want to dump all options use ``--full``.
+
+.. code-block:: bash
+
+  docker-compose exec admin flask mailu config-dump > mail-config.yml
+
 config-update
 -------------
 
-The sole purpose of this command is for importing users/aliases in bulk and synchronizing DB entries with external YAML template:
+The purpose of this command is for importing domain-, relay-, alias- and user-configuration in bulk and synchronizing DB entries with an external YAML template.
 
 .. code-block:: bash
 
-  cat mail-config.yml | docker-compose exec -T admin flask mailu config-update --delete-objects
+  docker exec -i $(docker-compose ps -q admin) flask mailu config-update -nvd < mail-config.yml
 
-where mail-config.yml looks like:
+*(The current version of docker-compose exec does not pass stdin correctly, so you have to user docker exec)*
 
-.. code-block:: bash
+mail-config.yml looks like:
+
+.. code-block:: yaml
+ 
+  domains:
+    - name: example.com
+      alternatives:
+        - alternative.example.com
 
   users:
-    - localpart: foo
+    - email: foo@example.com
-      domain: example.com
       password_hash: klkjhumnzxcjkajahsdqweqqwr
       hash_scheme: MD5-CRYPT
 
   aliases:
-    - localpart: alias1
+    - email: alias1@example.com
-      domain: example.com
       destination: "user1@example.com,user2@example.com"
 
-without ``--delete-object`` option config-update will only add/update new values but will *not* remove any entries missing in provided YAML input.
+  relays:
+    - name: relay.example.com
+      comment: test
+      smtp: mx.example.com
 
-Users
+You can use ``--dry-run`` to test your YAML without omitting any changes to the database.
------
+With ``--verbose`` config-update will show exactly what it changes in the database.
+Without ``--delete-object`` option config-update will only add/update new values but will *not* remove any entries missing in provided YAML input.
 
-following are additional parameters that could be defined for users:
+This is a complete YAML template with all additional parameters that could be defined:
 
-* comment
+.. code-block:: yaml
-* quota_bytes
-* global_admin
-* enable_imap
-* enable_pop
-* forward_enabled
-* forward_destination
-* reply_enabled
-* reply_subject
-* reply_body
-* displayed_name
-* spam_enabled
-* spam_threshold
 
-Alias
+  aliases:
------
+    - email: email@example.com
+      comment: ''
+      destination:
+        - address@example.com
+      wildcard: false
   
-additional fields:
+  domains:
+    - name: example.com
+      alternatives:
+        - alternative.tld
+      comment: ''
+      dkim_key: ''
+      max_aliases: -1
+      max_quota_bytes: 0
+      max_users: -1
+      signup_enabled: false
+  
+  relays:
+    - name: relay.example.com
+      comment: ''
+      smtp: mx.example.com
+  
+  users:
+    - email: postmaster@example.com
+      comment: ''
+      displayed_name: 'Postmaster'
+      enable_imap: true
+      enable_pop: false
+      enabled: true
+      fetches:
+        - id: 1
+          comment: 'test fetch'
+          username: fetch-user
+          host: other.example.com
+          password: 'secret'
+          port: 993
+          protocol: imap
+          tls: true
+          keep: true
+      forward_destination:
+        - address@remote.example.com
+      forward_enabled: true
+      forward_keep: true
+      global_admin: true
+      manager_of:
+        - example.com
+      password: '{BLF-CRYPT}$2b$12$...'
+      quota_bytes: 1000000000
+      reply_body: ''
+      reply_enabled: false
+      reply_enddate: 2999-12-31
+      reply_startdate: 1900-01-01
+      reply_subject: ''
+      spam_enabled: true
+      spam_threshold: 80
+      tokens:
+        - id: 1
+          comment: email-client
+          ip: 192.168.1.1
+          password: '$5$rounds=1000$...'
 
-* wildcard