| 1 |
# Foomuuri Monitor |
| 2 |
|
| 3 |
Foomuuri includes simple network connectivity monitor. It can monitor your |
| 4 |
internet connection by pinging some external server. Command can |
| 5 |
be run if network link goes up or down. Example |
| 6 |
[command](https://github.com/FoobarOy/foomuuri/blob/main/misc/monitor.event) |
| 7 |
to send an email notification to root is included in doc directory. Another |
| 8 |
examples are [multiple ISP](../example/multiple-isp.md) configurations and commands. |
| 9 |
|
| 10 |
|
| 11 |
## target |
| 12 |
|
| 13 |
Minimal configuration is: |
| 14 |
|
| 15 |
``` |
| 16 |
target google { |
| 17 |
command fping 8.8.4.4 |
| 18 |
} |
| 19 |
``` |
| 20 |
|
| 21 |
This creates monitor called `google` and runs `fping` command pinging |
| 22 |
IP 8.8.4.4 every second. Foomuuri parses its output and logs up and down |
| 23 |
events. Multiple targets can be defined. |
| 24 |
|
| 25 |
Better real life example is: |
| 26 |
|
| 27 |
``` |
| 28 |
target my-isp-router { |
| 29 |
command fping --interval=2000 172.25.31.149 |
| 30 |
command_up /etc/foomuuri/monitor.event |
| 31 |
command_down /etc/foomuuri/monitor.event |
| 32 |
} |
| 33 |
``` |
| 34 |
|
| 35 |
This pings IP 172.25.31.149 every two seconds and runs `monitor.event` |
| 36 |
command when link goes up or down. That command sends an email notification |
| 37 |
to root. |
| 38 |
|
| 39 |
See `man fping` or its [website](https://www.fping.org/) for description |
| 40 |
of `fping` parameters. Foomuuri supports both `interval` and `squiet` modes. |
| 41 |
It is recommended to use full seconds in `--interval`. |
| 42 |
|
| 43 |
"Up" and "down" are defined with parameters: |
| 44 |
|
| 45 |
``` |
| 46 |
target my-isp-router { |
| 47 |
history_size 100 # how many results are saved |
| 48 |
history_up 80 # count of UPs => n => UP |
| 49 |
history_down 30 # count of DOWNs >= n => DOWN |
| 50 |
consecutive_up 20 # last n were UP => UP |
| 51 |
consecutive_down 10 # last n were DOWN => DOWN |
| 52 |
... |
| 53 |
} |
| 54 |
``` |
| 55 |
|
| 56 |
Target is considered up if 80 of the last 100 pings were successful (allowing |
| 57 |
failures in between) and last 20 pings were successful (no failures allowed). |
| 58 |
|
| 59 |
Target is considered down if 30 of the last 100 pings were failures or |
| 60 |
last 10 pings were failures. |
| 61 |
|
| 62 |
`curl` and other programs can also be used instead of `fping`. See example |
| 63 |
[shell script](https://github.com/FoobarOy/foomuuri/blob/main/misc/monitor-example-command.sh) |
| 64 |
how to use them. |
| 65 |
|
| 66 |
It is recommended to use IP address instead of hostname as `fping` target. |
| 67 |
Hostname lookup will fail if network is down when `fping` starts. Foomuuri |
| 68 |
will handle this but it will cause 30 second delay and possible `fping` |
| 69 |
restart loop. |
| 70 |
|
| 71 |
Optional `command_down_interval` can be specified. Foomuuri will run it every |
| 72 |
`down_interval` seconds (default to 600, every 10 minutes). Example: |
| 73 |
|
| 74 |
``` |
| 75 |
target my-isp-router { |
| 76 |
# Connectivity is still down. Ask NetworkManager to re-initialize |
| 77 |
# eth0 connection. |
| 78 |
command_down_interval nmcli connection up eth0 |
| 79 |
|
| 80 |
# Run it every 15 minutes |
| 81 |
down_interval 900 |
| 82 |
... |
| 83 |
} |
| 84 |
``` |
| 85 |
|
| 86 |
Up/down command receives status information in environment variables: |
| 87 |
|
| 88 |
* `FOOMUURI_CHANGE_TYPE`: type `target` or `group` |
| 89 |
* `FOOMUURI_CHANGE_NAME`: name of target or group changing state |
| 90 |
* `FOOMUURI_CHANGE_STATE`: state `up` or `down` |
| 91 |
* `FOOMUURI_CHANGE_LOG`: extra logging information |
| 92 |
* `FOOMUURI_CHANGE_HISTORY`: list of `!` (error) or `.` (ok) |
| 93 |
indicating status of last checks |
| 94 |
* `FOOMUURI_ALL_TARGET`: list of all configured targets |
| 95 |
* `FOOMUURI_ALL_GROUP`: list of all configured groups |
| 96 |
* `FOOMUURI_TARGET_xxx`: state `up` or `down` for target `xxx` |
| 97 |
* `FOOMUURI_GROUP_xxx`: state `up` or `down` for group `xxx` |
| 98 |
|
| 99 |
Only single command can be specified. If you need to run multiple commands |
| 100 |
use a shell wrapper script to run them. |
| 101 |
|
| 102 |
Monitor statistics are written to a file once a minute. |
| 103 |
|
| 104 |
|
| 105 |
## group |
| 106 |
|
| 107 |
Multiple monitor [targets](monitor.md#target) can be grouped to single |
| 108 |
monitor. Example: |
| 109 |
|
| 110 |
``` |
| 111 |
group my-isp-group { |
| 112 |
target my-isp-router google |
| 113 |
command_up /etc/foomuuri/monitor.event |
| 114 |
command_down /etc/foomuuri/monitor.event |
| 115 |
} |
| 116 |
``` |
| 117 |
|
| 118 |
This creates a monitor called `my-isp-group` which includes two targets. |
| 119 |
Group is considered up if any of the targets is up. It is considered down |
| 120 |
if all of the targets are down. It is usually safer to run up and down |
| 121 |
commands in `group {}` with multiple targets than in single `target {}`. |
| 122 |
|
| 123 |
Optional `command_down_interval` and `down_interval` can also be defined. |
| 124 |
See [above](monitor.md#target) for description. |