added better documentation for user groups #189

README.md

@@ -50,6 +50,7 @@ Read the documentation below for more options.
             - [reportAlerta](docs/configuration.md#reportalerta)
             - [reportWebex](docs/configuration.md#reportwebex)
     - [Process/Uptime monitoring](docs/process-monitors.md)
+    - [Notification user groups](docs/usergroups.md)
 - [More information for developers](docs/develop.md)
     - [All npm commands](docs/develop.md#all-npm-commands)
 

docs/prefixes.md

@@ -71,7 +71,7 @@ Below the complete list of attributes (the dot notation is used to represent yml
 | path.matchDescription | The description that will be reported in the alert in case the regex test results in a match. | A string | No |
 | path.maxLength | The maximum length allowed for an AS path. Longer paths will trigger an alert. | A number | No |
 | path.minLength | The minimum length allowed for an AS path. Shorter paths will trigger an alert. | A number | No |
-| group | The name of the group that will receive alerts about this monitored prefix. By default all alerts are sent to the "default" group. | A string | No |
+| group | The name of the group that will receive alerts about this monitored prefix. By default all alerts are sent to the "default" group. See [here](usergroups.md).| A string | No |
 
 
 ### Options entry

docs/usergroups.md

@@ -0,0 +1,123 @@
+# User Groups
+
+BGPalerter supports user groups. With user groups you can:
+* Notify only specific users about specific prefixes.
+* Notify only specific users about specific type of alerts.
+
+By default all communications will use the default group, so it is not mandatory to configure any user group.
+Note that the default group is used also for administrative and error communications. 
+Hence, it is important to set user groups in case you want to monitor resources of your customers and you want to forward to them the alerts without sending them administrative communications.
+
+## Notify only specific users about specific prefixes
+
+Example of configuration.
+
+In prefixes.yml you can associate different groups to different resources.
+
+```yml
+165.254.225.0/24:
+  description: my description 1
+  asn: 2914
+  ignoreMorespecifics: false
+  ignore: false
+  group: group1
+ 
+165.254.255.0/24:
+  description: my description 2
+  asn: 2914
+  ignoreMorespecifics: false
+  ignore: false
+  group: group1
+ 
+192.147.168.0/24:
+  description: my description 3
+  asn: 15562
+  ignoreMorespecifics: false
+  ignore: false
+  group: group2
+
+
+options:
+  monitorASns:
+    2914:
+      group: group1
+    15562:
+      group: group2
+```
+
+
+In config.yml you have to specify the groups in the report modules.
+
+```yml
+reports:
+  - file: reportEmail
+    channels:
+      - hijack
+      - newprefix
+    params:
+      notifiedEmails:
+        default:
+          - admin@org.com
+        group1:
+          - joh@example.com
+          - max@example.com
+        group2:
+          - al@org.net
+
+ - file: reportSlack
+   channels:
+     - hijack
+     - newprefix
+   params:
+      hooks:
+        default: _SLACK_WEBOOK_FOR_ADMIN_
+        group1: _SLACK_WEBOOK_FOR_GROUP1_
+        group2: _SLACK_WEBOOK_FOR_GROUP2_
+```
+
+
+## Notify only specific users about specific type of alerts
+
+It's essentially the same configuration of above, except you have to duplicate report components, each serving a subset of the channels.
+
+```yml
+ - file: reportSlack
+   channels:
+     - hijack
+   params:
+      hooks:
+        default: _SLACK_WEBOOK_FOR_ADMIN_
+        group1: _SLACK_WEBOOK_FOR_GROUP2_
+
+ - file: reportSlack
+   channels:
+     - newprefix
+   params:
+      hooks:
+        default: _SLACK_WEBOOK_FOR_ADMIN_
+        group2: _SLACK_WEBOOK_FOR_GROUP1_
+```
+
+You can also split the notification across different reporting mechanism based on their type.
+
+```yml
+reports:
+  - file: reportEmail
+    channels:
+      - newprefix
+    params:
+      notifiedEmails:
+        default:
+          - admin@org.com
+        group1:
+          - joh@example.com
+          - max@example.com
+
+ - file: reportSlack
+   channels:
+     - hijack
+   params:
+      hooks:
+        default: _SLACK_WEBOOK_FOR_ADMIN_
+        group2: _SLACK_WEBOOK_FOR_GROUP2_
+```