nttgin-BGPalerter/docs/prefixes.md

# <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 |


## <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 listy in [config.yml](https://github.com/nttgin/BGPalerter/blob/master/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. By default all alerts are sent to the "default" group. 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).