From c57611e1158c14728cb77580c63fa1ba1e1a062a Mon Sep 17 00:00:00 2001 From: Massimo Candela Date: Sun, 13 Dec 2020 05:48:25 +0100 Subject: [PATCH] minor changes to text --- README.md | 2 +- docs/configuration.md | 28 ++++++++++++++-------------- docs/context.md | 6 +++--- docs/installation.md | 10 +++++----- docs/node.md | 6 +++--- docs/path-matching.md | 2 +- docs/prefixes.md | 4 ++-- docs/process-monitors.md | 2 +- docs/release-process.md | 2 +- docs/research.md | 8 ++++---- docs/ris-disconnections.md | 2 +- src/inputs/input.js | 7 ++++--- src/monitors/monitor.js | 2 +- 13 files changed, 41 insertions(+), 40 deletions(-) diff --git a/README.md b/README.md index e9201a2..3e38c16 100644 --- a/README.md +++ b/README.md @@ -27,7 +27,7 @@ Instead, if you want to run the source code (which is completely open) or develo 1. Download the binary [here](https://github.com/nttgin/BGPalerter/releases) (be sure to select the one for your OS) -2. Execute the binary (e.g. `chmod +x bgpalerter-linux-x64 && ./bgpalerter-linux-x64`) +2. Execute the binary (e.g., `chmod +x bgpalerter-linux-x64 && ./bgpalerter-linux-x64`) The first time you run it, the auto-configuration will start. diff --git a/docs/configuration.md b/docs/configuration.md index 7491322..fa6959e 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -15,8 +15,8 @@ The following are common parameters which it is possible to specify in the confi |logging.maxFileSizeMB| Indicates the maximum file size in MB allowed before to be rotated. This allows to rotate files when logRotatePattern still the same but the file is too big | An integer | 15 | Yes | |logging.maxRetainedFiles| Indicates the maximum amount of log files retained. When this threshold is passed, files are deleted. | An integer | 10 | Yes | |logging.useUTC| If set to true, logs will be reported in UTC time. Is set to false or missing, the timezone of the machine will be used. This parameter affects only the timestamp reported at the beginning of each log entry, it doesn't affect the time reported in the data/alerts which is always in UTC. | A boolean | true | No | -|checkForUpdatesAtBoot| Indicates if at each booth the application should check for updates. If an update is available, a notification will be sent to the default group. If you restart the process often (e.g. debugging, experimenting etc.) set this to false to avoid notifications. Anyway, BGPalerter checks for updates every 10 days.| A boolean | true | Yes | -|processMonitors| A list of modules allowing various ways to check for the status of BGPalerter (e.g. API, heartbeat). See [here](process-monitors.md) for more information. | | | No | +|checkForUpdatesAtBoot| Indicates if at each booth the application should check for updates. If an update is available, a notification will be sent to the default group. If you restart the process often (e.g., debugging, experimenting etc.) set this to false to avoid notifications. Anyway, BGPalerter checks for updates every 10 days.| A boolean | true | Yes | +|processMonitors| A list of modules allowing various ways to check for the status of BGPalerter (e.g., API, heartbeat). See [here](process-monitors.md) for more information. | | | No | |httpProxy| Defines the HTTP/HTTPS proxy server to be used by BGPalerter and its submodules (reporters/connectors/monitors). See [here](http-proxy.md) for more information. | A string | http://usr:psw@ prxy.org:8080 | No | |volume| Defines a directory that will contain the data that needs persistence. For example, configuration files and logs will be created in such directory (default to "./"). | A string | /home/bgpalerter/ | No | |persistStatus| If set to true, when BGPalerter is restarted the list of alerts already sent is recovered. This avoids duplicated alerts. The process must be able to write on disc inside `.cache/`. | A boolean | true | No | @@ -33,7 +33,7 @@ The following are advanced parameters, please don't touch them if you are not do |pidFile| A file where the PID of the BGP alerter master process is recorded. | A string | bgpalerter.pid | No | |maxMessagesPerSecond| A cap to the BGP messages received, over such cap the messages will be dropped. The default value is way above any production rate. Changing this value may be useful only for research measurements on the entire address space. | An integer | 6000 | No | |multiProcess| If set to true, the processing of the BGP messages will be distributed on two processes. This may be useful for research measurements on the entire address space. It is discouraged to set this to true for normal production monitoring. | A boolean | false | No | -|fadeOffSeconds| If an alert is generated but cannot be yet squashed (e.g. not reached yet the `thresholdMinPeers`), it is inserted in a temporary list which is garbage collected after the amount of seconds expressed in `fadeOffSeconds`. Due to BGP propagation times, values below 5 minutes can result in false negatives.| An integer | 360 | No | +|fadeOffSeconds| If an alert is generated but cannot be yet squashed (e.g., not reached yet the `thresholdMinPeers`), it is inserted in a temporary list which is garbage collected after the amount of seconds expressed in `fadeOffSeconds`. Due to BGP propagation times, values below 5 minutes can result in false negatives.| An integer | 360 | No | |checkFadeOffGroupsSeconds| Amount of seconds after which the process checks for fading off alerts. | An integer | 30 | No | @@ -44,7 +44,7 @@ You can compose the tool with 3 main components: connectors, monitors, and repor * Connectors retrieve/listen to the data from different sources and transform them to a common format. * 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. Reports can also provide the data triggering such alerts. +* Reports send/store the alerts, e.g., by email or to a file. Reports can also provide the data triggering such alerts. > 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. @@ -228,7 +228,7 @@ In particular, it will monitor for all the declared prefixes and will trigger an > description: an example > ignoreMorespecifics: false > ``` -> If in config.yml monitorNewPrefix is enabled you will receive alerts every time a more specific prefix (e.g. 50.82.4.0/24) is announced by AS58302. +> If in config.yml monitorNewPrefix is enabled you will receive alerts every time a more specific prefix (e.g., 50.82.4.0/24) is announced by AS58302. Example of alert: @@ -245,7 +245,7 @@ Parameters for this monitor module: #### monitorAS This monitor will listen for all announcements produced by the monitored Autonomous Systems and will detect when a prefix, which is not in the monitored prefixes list, is announced. -This is useful if you want to be alerted in case your AS starts announcing something you didn't intend to announce (e.g. misconfiguration, typo). +This is useful if you want to be alerted in case your AS starts announcing something you didn't intend to announce (e.g., misconfiguration, typo). > Example: @@ -305,7 +305,7 @@ This monitor is particularly useful when: > If in config.yml monitorRPKI is enabled, you will receive alerts every time: > * 103.21.244.0/24 is announced and it is not covered by ROAs, or the announcement is RPKI invalid; > * AS13335 announces something that is not covered by ROAs, or the announcement is RPKI invalid; -> * A prefix you announce used to be covered by a ROA but such ROA is no longer available (e.g. RPKI repositories past failures: [ARIN](https://www.arin.net/announcements/20200813/), [RIPE NCC](https://www.ripe.net/support/service-announcements/accidental-roa-deletion)) +> * A prefix you announce used to be covered by a ROA but such ROA is no longer available (e.g., RPKI repositories past failures: [ARIN](https://www.arin.net/announcements/20200813/), [RIPE NCC](https://www.ripe.net/support/service-announcements/accidental-roa-deletion)) Examples of alerts: @@ -322,7 +322,7 @@ Parameters for this monitor module: |checkUncovered| If set to true, the monitor will alert also for prefixes not covered by ROAs in addition of RPKI invalid prefixes. | |thresholdMinPeers| Minimum number of peers that need to see the BGP update before to trigger an alert. | |maxDataSamples| Maximum number of collected BGP messages for each alert which doesn't reach yet the `thresholdMinPeers`. Default to 1000. As soon as the `thresholdMinPeers` is reached, the collected BGP messages are flushed, independently from the value of `maxDataSamples`.| -|cacheValidPrefixesSeconds| Amount of seconds ROAs get cached in order to identify RPKI repository malfunctions (e.g. disappearing ROAs). Default to 7 days. | +|cacheValidPrefixesSeconds| Amount of seconds ROAs get cached in order to identify RPKI repository malfunctions (e.g., disappearing ROAs). Default to 7 days. | #### monitorROAS @@ -357,7 +357,7 @@ Example of alerts: ### Reports -Reports send/store the alerts, e.g. by email or to a file. Reports can also provide the data triggering such alerts. +Reports send/store the alerts, e.g., by email or to a file. Reports can also provide the data triggering such alerts. After configuring a report module, you can run the BGPalerter binary with the option `-t` to test the configuration. This will generate fake alerts. [Read more here](installation.md#bgpalerter-parameters). @@ -421,9 +421,9 @@ Parameters for this report module: |Parameter| Description| |---|---| -|host| Host of the Kafka instance/broker (e.g. localhost).| -|port| Port of the Kafka instance/broker (e.g. 9092).| -|topics| A dictionary containing a mapping from BGPalerter channels to Kafka topics (e.g. `hijack: hijack-topic`). By default all channels are sent to the topic `bgpalerter` (`default: bgpalerter`) | +|host| Host of the Kafka instance/broker (e.g., localhost).| +|port| Port of the Kafka instance/broker (e.g., 9092).| +|topics| A dictionary containing a mapping from BGPalerter channels to Kafka topics (e.g., `hijack: hijack-topic`). By default all channels are sent to the topic `bgpalerter` (`default: bgpalerter`) | #### reportSyslog @@ -434,8 +434,8 @@ Parameters for this report module: |Parameter| Description| |---|---| |showPaths| Amount of AS_PATHs to report in the alert (0 to disable). | -|host| Host of the Syslog server (e.g. localhost).| -|port| Port of the Syslog server (e.g. 514).| +|host| Host of the Syslog server (e.g., localhost).| +|port| Port of the Syslog server (e.g., 514).| |transport| The transport protocol to use. Two options: `udp` or `tcp`| |templates| A dictionary containing string templates for each BGPalerter channels. If a channel doesn't have a template defined, the `default` template will be used (see `config.yml.example` for more details). | diff --git a/docs/context.md b/docs/context.md index 708c4db..41a3ab7 100644 --- a/docs/context.md +++ b/docs/context.md @@ -16,11 +16,11 @@ Such tags are reported in the table below. | paths | The AS Paths involved in the alert | | pathNumber | The count of AS Paths in the alert | | peers | The number of peers that were able to see the issue | -| neworigin | The AS announcing the monitored prefix (e.g. in case of a hijack, `neworigin` will contain the hijacker, `asn` will contain the usual origin) | -| newprefix | The prefix announced (e.g. in case of a hijack, `newprefix` will contain the more specific prefix used for the hijack, `prefix` will contain the usual prefix) | +| neworigin | The AS announcing the monitored prefix (e.g., in case of a hijack, `neworigin` will contain the hijacker, `asn` will contain the usual origin) | +| newprefix | The prefix announced (e.g., in case of a hijack, `newprefix` will contain the more specific prefix used for the hijack, `prefix` will contain the usual prefix) | | bgplay | The link to BGPlay on RIPEstat | Usage example: `The alert involves ${prefix} in ${earliest}` will be translated in something like `The alert involves 1.2.3.4/24 in 2020-04-14 04:02:13`. -> The same approach must be used to populate the templates available in config.yml. If you are writing a template for an API call, convert the JSON to string (e.g. '{"text": "${summary}"}'). +> The same approach must be used to populate the templates available in config.yml. If you are writing a template for an API call, convert the JSON to string (e.g., '{"text": "${summary}"}'). diff --git a/docs/installation.md b/docs/installation.md index f54902d..e1da5ed 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -4,7 +4,7 @@ 1. Download the binary [here](https://github.com/nttgin/BGPalerter/releases) (be sure to select the one for your OS) -2. Execute the binary (e.g. `chmod +x bgpalerter-linux-x64 && ./bgpalerter-linux-x64`) +2. Execute the binary (e.g., `chmod +x bgpalerter-linux-x64 && ./bgpalerter-linux-x64`) The first time you run it, the auto-configuration will start. ## Running BGPalerter from binaries - All steps @@ -15,7 +15,7 @@ The first time you run it, the auto-configuration will start. 2. Download [`config.yml.example`](https://raw.githubusercontent.com/nttgin/BGPalerter/master/config.yml.example) as `config.yml` (in the same directory of the binary) -3. Make the binary executable (e.g. `chmod +x bgpalerter-linux-x64`) +3. Make the binary executable (e.g., `chmod +x bgpalerter-linux-x64`) 4. Auto-configure it: `./bgpalerter-linux-x64 generate -a _YOUR_ASN_ -o prefixes.yml -i -m` @@ -30,7 +30,7 @@ Additionally, you can configure [BGPalerter to run as a Linux Serivce](linux-ser 2. Download [`config.yml.example`](https://raw.githubusercontent.com/nttgin/BGPalerter/master/config.yml.example) as `config.yml` (in the same directory of the binary) -3. Make the binary executable (e.g. `chmod +x bgpalerter-macos-x64`) +3. Make the binary executable (e.g., `chmod +x bgpalerter-macos-x64`) 4. Auto-configure it: `./bgpalerter-macos-x64 generate -a _YOUR_ASN_ -o prefixes.yml -i -m` @@ -78,7 +78,7 @@ docker run -i --name bgpalerter \ With this command, a new directory `./volume` will be created in the current position. Such directory will contain all the persistent data that BGPalerter will generate, including configuration and alert logs. -You can specify another directory by changing the directory before the colon in the -v flag (e.g. `-v _LOCATION_YOU_WANT_/volume:/opt/bgpalerter/volume`). +You can specify another directory by changing the directory before the colon in the -v flag (e.g., `-v _LOCATION_YOU_WANT_/volume:/opt/bgpalerter/volume`). The command above runs BGPalerter in interactive mode (`-i` flag), which is necessary if you want to run the auto configuration. @@ -97,7 +97,7 @@ docker run -i --name bgpalerter \ ``` The `uptimeApi` module has to be enabled in `volume/config.yml` as described [here](process-monitors.md). -Now you can monitor `http://127.0.0.1:8011/status` (e.g. in Nagios) to check the status of the BGPalerter monitoring. +Now you can monitor `http://127.0.0.1:8011/status` (e.g., in Nagios) to check the status of the BGPalerter monitoring. Such API may return a negative result when there is a misconfiguration or when BGPalerter failed to connect to the data repository. diff --git a/docs/node.md b/docs/node.md index c1eeb33..dd83d57 100644 --- a/docs/node.md +++ b/docs/node.md @@ -2,7 +2,7 @@ Some fast commands are below. The complete documentation (including other platforms) is [here](https://nodejs.org/en/download/) -## With apt (e.g. debian) +## With apt (e.g., debian) ```bash curl -sL https://deb.nodesource.com/setup_12.x | sudo bash - @@ -10,14 +10,14 @@ sudo apt install nodejs ``` -## With homebrew (e.g. macos) +## With homebrew (e.g., macos) ```bash brew update brew install node@12 ``` -## With yum (e.g. centos) +## With yum (e.g., centos) ```bash curl -sL https://deb.nodesource.com/setup_12.x | sudo bash - diff --git a/docs/path-matching.md b/docs/path-matching.md index 426a047..2af5fee 100644 --- a/docs/path-matching.md +++ b/docs/path-matching.md @@ -46,7 +46,7 @@ Each matching rule is composed of: If you want to specify multiple conditions in AND in the same match parameter, you can use the positive lookahead construct offered natively by regular expressions. A positive lookahead is in the form `(?=exp1)(?=exp2)` where `exp1` and `exp2` are regular expressions. -Positive lookaheads work also for expressing negative conditions (e.g. `(?!exp)`), but in most of the cases this is redundant with the `notMatch` parameter. +Positive lookaheads work also for expressing negative conditions (e.g., `(?!exp)`), but in most of the cases this is redundant with the `notMatch` parameter. diff --git a/docs/prefixes.md b/docs/prefixes.md index 1b6a887..2c01f90 100644 --- a/docs/prefixes.md +++ b/docs/prefixes.md @@ -3,8 +3,8 @@ ## 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`). +* 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". diff --git a/docs/process-monitors.md b/docs/process-monitors.md index 45e88af..91ae154 100644 --- a/docs/process-monitors.md +++ b/docs/process-monitors.md @@ -74,7 +74,7 @@ Parameters for this module are: The uptimeHealthcheck module is a component that will start polling a provided URL at a regular interval. -This can be used to send a heartbeat signal to a monitoring system (e.g. https://healthchecks.io/). +This can be used to send a heartbeat signal to a monitoring system (e.g., https://healthchecks.io/). If there is any warning about any component activated in BGPalerter, the heartbeat will not be issued (independently from the fact that the process is still running). diff --git a/docs/release-process.md b/docs/release-process.md index 27d007b..f05caa2 100644 --- a/docs/release-process.md +++ b/docs/release-process.md @@ -41,7 +41,7 @@ The release number is composed of 3 digis `x.x.x`: * The third number identifies a minor release. The third number is incremented when there are changes which don't introduce any new functionality but improve the available ones. ### Patching -In the event a serious bug (e.g. affecting one of the core functionalities) is discovered in a released version, we will not follow the timing described above and release as soon as possible a minor release. +In the event a serious bug (e.g., affecting one of the core functionalities) is discovered in a released version, we will not follow the timing described above and release as soon as possible a minor release. Minor releases are anyway tested and deployed for the monitoring of our network. A minor release can also be released as a part of the normal release cycle in case there are no new features to justify a major release. diff --git a/docs/research.md b/docs/research.md index e94e715..b7aaf09 100644 --- a/docs/research.md +++ b/docs/research.md @@ -30,7 +30,7 @@ If during your analysis you will find a warning of messages dropped in the logs, If the memory consumption during your analysis increases drastically, you may want to: 1) Check your code for memory leaks -2) Check you are not doing many async calls accumulating in the stack (e.g. if you monitor the entire v6 address space, like on the example above, you cannot do a single network call for each BGP message received. You can instead bundle together multiple calls or pre-filter better). +2) Check you are not doing many async calls accumulating in the stack (e.g., if you monitor the entire v6 address space, like on the example above, you cannot do a single network call for each BGP message received. You can instead bundle together multiple calls or pre-filter better). 3) Check that the `squashAlerts` of your monitor component is working as expected. In particular, if the squashAlerts methods returns null it means the bucket of BGP messages is not yet ready for squashing, remaining in memory. See below for more information. 4) Reduce the `fadeOffSeconds`. This will drop all the BGP messages that took too long to be squashed by `squashAlerts`. @@ -62,7 +62,7 @@ export default class myMonitor extends Monitor { // It MUST extend Monitor filter = (message) => { /* Pre-filtering. This filtering is blocking since it happens synchronously. * Make this filtering as tight as possible without involving external resources - * (e.g. do NOT do database or API call here). For example base your filtering + * (e.g., do NOT do database or API call here). For example base your filtering * on the properties of the BGP message received */ return message.type === 'announcement'; }; @@ -75,7 +75,7 @@ export default class myMonitor extends Monitor { // It MUST extend Monitor * squash attempt is going to be when another alert with the same signature is received. * With this method you can collect alerts and decide when it's time to send them. */ - if (alerts.length > 5) { // Useless condition just to explain the concept (e.g. you could instead check how many different peers saw the issue before to report it) + if (alerts.length > 5) { // Useless condition just to explain the concept (e.g., you could instead check how many different peers saw the issue before to report it) return "summary of the alerts"; } @@ -109,5 +109,5 @@ export default class myMonitor extends Monitor { // It MUST extend Monitor Useful for research are the following pre-made monitors: * monitorPath - will detect specific conditions on AS paths -* monitorPassthrough - will let everything pass to the report component. This is useful if you want to use BGPalerter as a data connector and you want to pass the data to another application (e.g. you can send them to Kafka with `reportKafka` or you can create a report wit a `console.log` to pipe everything into standard output) +* monitorPassthrough - will let everything pass to the report component. This is useful if you want to use BGPalerter as a data connector and you want to pass the data to another application (e.g., you can send them to Kafka with `reportKafka` or you can create a report wit a `console.log` to pipe everything into standard output) * monitorRPKI - will detect RPKI invalid announcements. I use this on the entire v4 and v6 address space. It can be used as an example of "complex" monitoring. \ No newline at end of file diff --git a/docs/ris-disconnections.md b/docs/ris-disconnections.md index aba5cf6..608c462 100644 --- a/docs/ris-disconnections.md +++ b/docs/ris-disconnections.md @@ -5,7 +5,7 @@ Sometimes among the error logs you will find RIS disconnection logs (usually err The following causes are possible: 1) **Network issues.** The machine where BGPalerter is running loses connectivity (maybe just for a few seconds). -2) **You are monitoring something that produces too many BGP updates** (e.g. your prefixes are not stable or constantly re-announced). In such cases you may be too slow in consuming the data and the server disconnects you to flush the buffer. +2) **You are monitoring something that produces too many BGP updates** (e.g., your prefixes are not stable or constantly re-announced). In such cases you may be too slow in consuming the data and the server disconnects you to flush the buffer. Anyway, unfortunately sometimes this happens without an explanation due to RIPE RIS instabilities. This has been reported to the RIPE RIS team. diff --git a/src/inputs/input.js b/src/inputs/input.js index 2e9dec5..a95fe31 100644 --- a/src/inputs/input.js +++ b/src/inputs/input.js @@ -181,7 +181,7 @@ export default class Input { { type: 'input', name: 'asns', - message: "Which Autonomous System(s) you want to monitor? (comma-separated, e.g. 2914,3333)", + message: "Which Autonomous System(s) you want to monitor? (comma-separated, e.g., 2914,3333)", default: null, validate: function(value) { const asns = value.split(",").filter(i => i !== "" && !isNaN(i)); @@ -248,12 +248,13 @@ export default class Input { return this.retrieve() .then(oldPrefixList => { const inputParameters = oldPrefixList.options.generate; - inputParameters.httpProxy = this.config.httpProxy || null; if (!inputParameters) { - throw new Error("The prefix list cannot be refreshed because it was not generated automatically or the cache has been deleted."); + throw new Error("The prefix list cannot be refreshed because it was not generated automatically."); } + inputParameters.httpProxy = this.config.httpProxy || null; + inputParameters.logger = (message) => { // Nothing, ignore logs in this case (too many otherwise) }; diff --git a/src/monitors/monitor.js b/src/monitors/monitor.js index 526eaf4..695226e 100644 --- a/src/monitors/monitor.js +++ b/src/monitors/monitor.js @@ -56,7 +56,7 @@ export default class Monitor { this.alerts = {}; // Dictionary containing the alerts . The id is the "group" key of the alert. this.sent = {}; // Dictionary containing the last sent unix timestamp of each group this.truncated = {}; // Dictionary containing if the alerts Array for "id" is truncated according to maxDataSamples - this.fadeOff = {}; // Dictionary containing the last alert unix timestamp of each group which contains alerts that have been triggered but are not ready yet to be sent (e.g. thresholdMinPeers not yet reached) + this.fadeOff = {}; // Dictionary containing the last alert unix timestamp of each group which contains alerts that have been triggered but are not ready yet to be sent (e.g., thresholdMinPeers not yet reached) this._retrieveStatus(); this.internalConfig = {