Debian Codegraph @

docs/tool/monitor.md

raw
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.