mirror of
https://github.com/nttgin/BGPalerter.git
synced 2024-05-19 06:50:08 +00:00
112 lines
6.3 KiB
Markdown
112 lines
6.3 KiB
Markdown
# <a name="prefixes"></a>Monitored Prefixes List
|
|
|
|
## <a name="generate"></a>Auto-generate prefixes list
|
|
|
|
To auto generate the monitored prefixes file (by default called `prefixes.yml`) execute:
|
|
* If you are using the binary `./bgpalerter-linux-x64 generate -a ASN(S) -o OUTPUT_FILE` (e.g., `./bgpalerter-linux-x64 generate -a 2914 -o prefixes.yml`).
|
|
* If you are using the source code `npm run generate-prefixes -- --a ASN(S) --o OUTPUT_FILE` (e.g., `npm run generate-prefixes -- --a 2914 --o prefixes.yml`).
|
|
|
|
The script will detect whatever is currently announced by the provided AS and will take this as "the expected status".
|
|
|
|
A warning will be triggered in case of not valid RPKI prefixes, anyway, you should always check the generated list, especially if you are using the option `-i`
|
|
|
|
Below the list of possible parameters. **Remember to prepend them with a `--` instead of `-` if you are using the source code version.**
|
|
|
|
| Parameter | Description | Expected format | Example | Required |
|
|
|---|---|---|---|---|
|
|
| -o | The YAML output file. | A string ending in ".yml" | prefixes.yml | Yes |
|
|
| -a | The AS number(s) you want to generate the list for. | A comma-separated list of integers | 2914,3333 | No (one among -a, -p, -l is required) |
|
|
| -e | Prefixes to exclude from the list. | A comma-separated list of prefixes | 165.254.255.0/24,192.147.168.0/24 | No |
|
|
| -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 |
|
|
| -x | HTTP/HTTPS proxy server to use. | A string | http://username:password@proxy.example.org:8080 | No |
|
|
| -A | Append the new configuration to the old one. E.g. you can use this option to add another AS. | Nothing | | No |
|
|
| -D | Enable debug mode. All queries executed in background will be shown. | Nothing | | No |
|
|
| -H | Use historical visibility data for generating prefix list (prefixes visible in the last week). Useful in case the prefix generation process returns an empty dataset. | Nothing | | No |
|
|
| -g | The name of the user group that will be assigned to all the generated rules. See [here](usergroups.md). | A string | noc | No |
|
|
| -u | Calculate all upstream ASes and enable detection of new left-side ASes. See [here](path-neighbors.md). | Nothing | | No |
|
|
| -n | Calculate all downstream ASes and enable detection of new right-side ASes. See [here](path-neighbors.md). | Nothing | | No |
|
|
|
|
|
|
## <a name="prefixes-fields"></a>Prefixes list fields
|
|
|
|
The prefix list is a file containing a series of blocks like the one below, one for each prefix to monitor.
|
|
|
|
>Tip: Only the attributes description, asn, and ignoreMorespecifics are mandatory.
|
|
|
|
```
|
|
165.254.255.0/24:
|
|
description: Rome peering
|
|
asn: 2914
|
|
ignoreMorespecifics: false
|
|
ignore: false
|
|
group: aUserGroup
|
|
excludeMonitors:
|
|
- withdrawal-detection
|
|
path:
|
|
match: ".*2194,1234$"
|
|
notMatch: ".*5054.*"
|
|
matchDescription: detected scrubbing center
|
|
maxLength: 128
|
|
minLength: 2
|
|
```
|
|
|
|
###### <a name="array"></a>
|
|
> Tip: In yml, arrays of values are described with dashes, like below:
|
|
```
|
|
asn:
|
|
- 2914
|
|
- 3333
|
|
```
|
|
|
|
Below the complete list of attributes (the dot notation is used to represent yml sub-dictionaries):
|
|
|
|
| Attribute | Description | Expected type | Required |
|
|
|---|---|---|---|
|
|
| asn | The expected origin AS(es) of the prefix. | An integer or an array of integers. | Yes |
|
|
| description | A description that will be reported. in the alerts | A string | Yes |
|
|
| ignoreMorespecifics | Prefixes more specific of the current one will be excluded from monitoring. | A boolean | Yes |
|
|
| ignore | Exclude the current prefix from monitoring. Useful when you are monitoring a prefix and you want to exclude a particular sub-prefix. | A boolean | No |
|
|
| includeMonitors | The list of monitors you want to run on this prefix. If this attribute is not declared, all monitors will be used. Not compatible with excludeMonitors. | An array of strings (monitors name according to config.yml) | No |
|
|
| excludeMonitors | The list of monitors you want to exclude on this prefix. Not compatible with includeMonitors. Use monitors `name` attributes, as defined in the monitor list in [config.yml](https://github.com/nttgin/BGPalerter/blob/main/config.yml.example). | An array of strings (monitors name according to config.yml) | No |
|
|
| path | A list path matching rules, read more [here](path-matching.md). | | No |
|
|
| group | The name of the group that will receive alerts about this monitored prefix. See [here](usergroups.md).| 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 prefixes) of Autonomous Systems.
|
|
|
|
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.
|
|
|
|
The monitor in charge of doing this type of detection is [monitorAS (click for more information)](configuration.md#monitoras). |