diff --git a/docs/configuration.md b/docs/configuration.md index ad9fffc..fb42aca 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -31,6 +31,11 @@ You can compose the tool with 3 main components: connectors, monitors, and repor * Monitors analyze the data flow and produce alerts. Different monitors try to detect different issues. * Reports send/store the alerts, e.g. by email or to a file. +> In config.yml.example there are all the possible components declarations (similar to the one of the example below). You can enable the various components by uncommenting the related block. + + +Example of composition: + ```yaml connectors: - file: connectorRIS @@ -134,6 +139,7 @@ Parameters for this monitor module: #### monitorNewPrefix This monitor has the logic to detect unexpected change of configuration in the form of new more specific prefixes announced by the correct AS. + In particular, it will monitor for all the declared prefixes and will trigger an alert when: * A sub-prefix of the monitored prefix starts to be announced by the same AS declared for the prefix. @@ -161,7 +167,7 @@ This is useful if you want to be alerted in case your AS starts announcing somet > Example: -> The prefixes list of BGPalerter has an entry such as: +> The prefixes list of BGPalerter has an options.monitorASns list declared, such as: > ```yaml > 50.82.0.0/20: > asn: 58302 @@ -176,6 +182,7 @@ This is useful if you want to be alerted in case your AS starts announcing somet > If in config.yml monitorAS is enabled, you will receive alerts every time a prefix not already part of the prefixes list is announced by AS58302. > If AS58302 starts announcing 45.230.23.0/24 an alert will be triggered. This happens because such prefix is not already monitored (it's not a sub prefix of 50.82.0.0/20). +You can generate the options block in the prefixes list automatically. Refer to the options `-s` and `-m` in the [auto genere prefixes documentation](prefixes.md#generate). Parameters for this monitor module: @@ -183,6 +190,8 @@ Parameters for this monitor module: |---|---| |thresholdMinPeers| Minimum number of peers that need to see the BGP update before to trigger an alert. | +This monitor is by default disabled. Uncomment the `monitorAS` block in `config.yml` to enable it (see [here](#composition)). + ### Reports diff --git a/docs/prefixes.md b/docs/prefixes.md index cd8eecf..261c0d2 100644 --- a/docs/prefixes.md +++ b/docs/prefixes.md @@ -20,6 +20,8 @@ Below the list of possible parameters. **Remember to prepend them with a `--` in | -i | Avoid monitoring delegated prefixes. If a more specific prefix is found and it results announced by an AS different from the one declared in -a, then set `ignore: true` and `ignoreMorespecifics: true` | Nothing | | No | -p | Prefixes for which the list will be generated | A comma-separated list of prefixes | 165.254.255.0/24,192.147.168.0/24 | No (one among -a, -p, -l is required) | | -l | A file containing the prefixes for which the list will be generated | A text file having a prefix for each line | prefixes.txt | No (one among -a, -p, -l is required) | +| -s | A list of ASns to be monitored. See [monitorASns](#monitorASns) for more information | A comma separated list of integer | 2914,3333 | No | +| -m | Monitor all ASns which are origin of at least one of the monitored prefixes. This option is the same of `-s` except that the list of ASns is automatically generated by detecting the origin AS of all the monitored prefixes. See [monitorASns](#monitorASns) for more information | Nothing | | No | ## Prefixes list fields @@ -43,7 +45,6 @@ The prefix list is a file containing a series of blocks like the one below, one matchDescription: detected scrubbing center maxLength: 128 minLength: 2 - ``` ###### @@ -73,6 +74,39 @@ Below the complete list of attributes (the dot notation is used to represent yml | 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 | +### Options entry + +Optionally the prefixes list can contain an `options` entry, such us: + +```yaml +options: + monitorASns: + 2914: + group: default +``` + +The `options` entry allows the configuration of additional monitoring options directly from the prefixes list file. + +| Option | Description | +|---|---| +| monitorASns | A dictionary of ASns to be monitored. Each entry of the dictionary has the ASn as key. Each value of the dictionary contains the monitoring settings.| + +#### monitorASns + +Allows for generic monitoring (not related to specific prefix) of Autonomous Systems. Please, refer to [monitorAS](configuration.md#monitoras) for more information. + +An example of monitorASns configuration is: + +```yaml +monitorASns: + 2914: + group: ntt + 3333: + group: ripencc +``` + +The AS2914 and AS3333 will be monitored. The alerts related to AS2914 will be sent to the "ntt" user group and the alerts for AS3333 to the "ripencc" user group. + ### Optimized regular expressions for AS path matching @@ -82,6 +116,6 @@ To drastically optimize the process, try to use one of the following regular exp * "789$" - match paths that originate with AS789 * "456" - match any path that traverses AS456 at any point -* "^123,456" - match paths where the last traversed ASNs were 123 and 456 (in that order) +* "^123,456" - match paths where the last traversed ASns were 123 and 456 (in that order) * "^123,456,789$" - match the exact path [123, 457, 789] * "[789,101112]" - match paths containing the AS_SET {789, 101112}