Skip to content

Usage # Limit alerts

Jump to bottom
Teemu Toivola edited this page Oct 22, 2022 · 1 revision

The --alert functionality, added in version 2.9, allows defining conditional behaviour depending on set traffic limits or estimates. The condition is evaluated during command execution (= not stored in the database) and makes it possible, for example, to send an email or perform other actions if a period specific traffic limit has been reached or is projected to be reached before the period ends.

Parameters explained

The usage description for the --alert functionality can be found from the vnstat man page and by executing vnstat --alert without any extra parameters. Usage examples are provided later on this page.

--alert requires 6 additional parameters in all cases:

  1. output mode
  2. exit code behaviour
  3. time period type
  4. condition to be evaluated
  5. limit
  6. unit for limit

In addition, an interface needs to be explicitly specified using the -i / --iface option.

Output mode

  • 0 - never output anything regardless of other parameters, possible errors will still be visible
  • 1 - always output current status even if condition isn't met
    • useful for status reports and testing
  • 2 - show output only if usage estimate exceeds limit
  • 3 - show output only if limit is exceeded

Exit code behaviour

  • 0 - always use exit status 0
    • mainly useful if no other commands are being chained to be executed depending on the vnstat command exit code
  • 1 - always use exit status 1
    • shouldn't be useful in most cases
  • 2 - use exit status 1 if usage estimate exceeds limit
  • 3 - use exit status 1 if limit is exceeded

Note that the exit status code will be either 0 or 1 depending on the selected option.

Time period type

Which time period is used for the condition evaluation.

  • h, hour or hourly for hours
  • d, day or daily for days
  • m, month or monthly for months
  • y, year or yearly for years

Note that the 5 minute time period isn't available for --alert.

Condition

Select which metric to compare with.

  • rx - received data
  • tx - transmitted data
  • total - sum of received and transmitted data
  • rx_estimate - estimate of received data by the end of the time period
  • tx_estimate - estimate of transmitted data by the end of the time period
  • total_estimate - estimate of sum of received and transmitted data by the end of the time period

Limit

Greater than zero integer number (= no decimals).

Unit for limit

All of the following units are supported:

  • B, KiB, MiB, GiB, TiB, PiB, EiB
  • B, KB, MB, GB, TB, PB, EB

Output explained

Using vnstat -i enp4s0 --alert 1 0 m total 5 GiB as command in an environment where the 5 GiB monhly limit hasn't been reached, the output looks the following:

   enp4s0 at 2022-10-09 21:35:00 for month 2022-10

     [===========--------------------------......................]

       monthly |       total      |   percentage   |   avg. rate
     ----------+------------------+----------------+--------------
          used |       926.73 MiB |          18.1% |    1.23 KiB/s
         limit |         5.00 GiB |                |    1.96 KiB/s
     remaining |         4.09 GiB |          81.9% |
     ----------+------------------+----------------+--------------
     estimated |         3.15 GiB |          63.0% |    1.23 KiB/s

The first line describes the interface name with the possible alias also shown if set. The timestamp following the interface name indicates the timestamp when the data was updated followed by information which time period is being tracked.

The bar on the third line fills with = according to usage so far while - represents the estimated usage at the end of the period if the average traffic rate stays the same. . is used as a filler for unused quota.

The table contains information of so far used data (926.73 MiB / 18.1%) and the average rate so far (1.23 KiB/s). The set limit 5.00 GiB is repeated following the maximum average rate (1.96 KiB/s). Remaining quota (4.09 GiB / 81.9%) is shown on the next line. Finally, if estimates are configured visible, the last line shows how much would be used by the end of the time period (3.15 GiB) if the average rate stays the same as it currently is (1.23 KiB/s).

Usage examples

Daily traffic report

With the following criterias and assumptions:

  • Used interface is eth0
  • There's a total (rx + tx) monthly quota of 500 GiB
  • The system has the sendmail command available configured

This results in the command being:

vnstat -i eth0 --alert 1 0 m total 500 GiB

For sending the output by email, the sendmail command is added with the recipient address:

vnstat -i eth0 --alert 1 0 m total 500 GiB | sendmail [email protected]

Finally, this can be combined as a cron entry for sending the report daily at midnight:

0 0 * * * vnstat -i eth0 --alert 1 0 m total 500 GiB | sendmail [email protected]

Command execution when quota reached

  • Used interface is eth0
  • There's a monthly quota of 2 TiB for transmitted data while received is ignored

This results in the command being:

vnstat -i eth0 --alert 0 3 m tx 2 TiB

Output mode is set to 0 as no output is wanted, exit code behaviour is set to 3 for indicating when the limit has been reached and allowing to chain commands:

vnstat -i eth0 --alert 0 3 m tx 2 TiB || systemctl stop nginx

Would result in systemctl stop nginx getting executed if more than 2 TiB of transmitted data has been seen for the current month when the command combination is executed while otherwise this wouldn't produce any output.

Clone this wiki locally